Implement a deterministic resource identifier codec with namespace isolation

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): access-control, backend, type-safety, advanced

Background

GuildPass access-control systems will eventually need to reference many kinds of protected resources, including communities, governance objects, channels, documents or external integrations.

Using unstructured strings for resource identifiers creates ambiguity and makes permission matching harder to validate safely.

This issue introduces a standalone namespaced resource identifier codec.

Problem

There is currently no canonical Core representation for identifiers such as community:abc, document:123 or nested resource paths.

Manual string concatenation can introduce escaping errors, namespace collisions and multiple textual representations for the same logical resource.

Expected Outcome

Implement a strongly typed resource identifier parser and formatter with explicit namespace and segment validation.

Suggested Implementation

A parsed identifier may resemble:

interface ResourceIdentifier {
  namespace: string;
  segments: string[];
}

The module should:

• define one canonical textual representation;
• validate namespace syntax;
• validate resource segments;
• define escaping or encoding rules for reserved delimiters;
• reject empty segments;
• impose maximum namespace, segment and total identifier lengths;
• support parse/format round trips;
• provide deterministic equality or canonical comparison helpers;
• reject malformed encodings;
• avoid filesystem/path traversal semantics accidentally leaking into resource identifiers;
• remain independent of actual resource persistence.

For example, if / is used as a segment delimiter, literal / inside a segment must either be forbidden or encoded unambiguously.

Acceptance Criteria

• Valid identifiers parse into the expected namespace and segments.
• Formatting produces one canonical representation.
• Parse/format round trips succeed.
• Empty namespaces and segments are rejected.
• Reserved delimiter handling is explicit and tested.
• Oversized identifiers are rejected.
• Malformed escaping or encoding is rejected safely.
• Canonically equivalent identifiers compare equally.
• Unit tests cover Unicode, reserved delimiters, malformed input and length boundaries.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No resource database model, API route or policy integration is introduced.

Likely Affected Files/Directories

packages/resource-id/ or equivalent isolated package
unit tests

Independence Requirement

This issue must be independently implementable from main and must not depend on a resource service, policy engine or another campaign contribution.

[bigboss-spec]

Hi Maintainer! I'm a senior developer with experience building high-quality, production-ready software. I'd love to take on this issue and deliver a clean, well-tested solution that aligns with the project's standards. Please assign it to me—I'm ready to get started and contribute effectively.

[ValJnr-dev1]

Hi Maintainer,

I’m a smart contract and full-stack developer and would love to contribute to this issue. I’m an experienced contributor with hands-on expertise in Rust, Soroban, Cairo, and TypeScript.

I’m passionate about building secure, scalable blockchain solutions, with a strong emphasis on writing clean and maintainable code. Based on the scope of this issue, I’m confident I can deliver a complete solution within 24 hours of assignment.

I’d greatly appreciate the opportunity to contribute and help move this forward.

[Agbasimere]

Can I work on this?

[grantfox-oss]

🦊 GrantFox — @bigboss-spec has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #388)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🦊 GrantFox — @Agbasimere has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #388)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.