docs: access management guide

[marc0olo]

Summary

• Covers caller identity model (user, canister, anonymous, management principals)
• Rejecting anonymous callers in both Motoko and Rust
• Rust guard attribute pattern for declarative access control
• Owner and role-based access control with complete examples in both languages
• Controller management via icp canister settings update
• canister_inspect_message with clear warnings about its limitations
• Debugging with whoami endpoint pattern

Sync recommendation

informed by dfinity/portal — docs/building-apps/best-practices/general.mdx + canister-security icskill

[marc0olo]

Review

Must-fix (2)

1. Missing Runtime import in Controller checks Motoko snippet (line ~214) — The code calls Runtime.trap(...) but only imports Principal. Needs import Runtime "mo:core/Runtime";.

2. Upstream comment format (line 339) — Missing em dash separator. Current: informed by dfinity/portal docs/.... Should be: informed by dfinity/portal — docs/.... Also, the content is heavily derived from the canister-security icskill, which should be acknowledged.

Suggestions (3)

3. Rust #[init] takes explicit owner: Principal — differs from Motoko's shared(msg) pattern. A brief note explaining the difference and how to pass the owner during deployment would help.

4. No Rust equivalent for controller checks — Motoko has Principal.isController but the Rust section doesn't show how to check controllers (requires management canister query). Worth noting the asymmetry.

5. Checklist vs guide format — Content brief said "checklist" but the page is a proper how-to guide, which is actually better for Diataxis. No change needed, just noting the deviation.

[marc0olo]

Additional suggestion: make principal type table more explicit

The current table doesn't make it easy to distinguish user vs canister principals. Since they look similar as opaque text, consider adding a format column:

Type	Format	Example	Meaning
User	Varies (self-authenticating)	wo5qg-ysjaa-aaaaa-...	Human with a cryptographic identity
Canister	10 bytes, ends in -cai	rrkah-fqaaa-aaaaa-aaaaq-cai	Another canister making an inter-canister call
Anonymous	Fixed	2vxsx-fae	Unauthenticated caller — no identity
Management	Fixed	aaaaa-aa	IC management canister (system calls)

This helps developers who need to distinguish caller types in their access control logic.

[marc0olo]

Feedback addressed:

• Added missing Runtime import in controller checks Motoko snippet
• Expanded principal types table with format column (self-authenticating vs 10-byte -cai suffix)
• Added note about Rust #[init] requiring explicit owner principal at deploy time
• Added note about Rust controller checks requiring management canister call, with link to onchain-calls page
• Fixed Upstream comment: added em dash separator, added icskills source