Share Link Access Architect

---
name: share-link-access-architect
description: 'Design guest/public share-link access for a multi-tenant SaaS — a CAPABILITY model where possession of an opaque, high-entropy, expiring, revocable token grants a fixed narrow scope, distinct from member RBAC: token design, ephemeral guest sessions (not memberships), optional password/OTP gating, per-link scope (which resource, which permission), enumeration/abuse defense, and audit. The link must expose exactly the shared resource and never become a hole into the rest of the tenant. Use when adding anyone-with-the-link view/comment/edit access for non-members (often unauthenticated), or designing the share token''s entropy, expiry, revocation, and gating. Do NOT use for MEMBER roles×permissions or impersonation/support access (authorization-matrix-designer), or for API credentials / webhook signing / partner keys (api-event-architect). Produces a design/spec; do not invent crypto primitives — use vetted ones.'
---

# Share-Link Access Architect

## Purpose

Design **guest/public share-link access** — the "anyone with the link can
view / comment / edit" surface — as a capability model: possession of an
opaque, unguessable, expiring, revocable token grants a single fixed, narrow
scope, with no tenant membership and no role. The deliverable is the token
design (entropy, expiry, revocation), the ephemeral guest-session model, an
optional password/OTP gate, the per-link scope binding, an enumeration/abuse
defense, and the audit contract. The two load-bearing properties: the token is
a bearer capability (unguessable and least-privileged, because whoever holds
it is the actor), and the link exposes exactly the shared resource — never a
path into the rest of the tenant. This is a design/spec deliverable; it uses
vetted cryptographic primitives, it does not invent them.

## Use When

- Use when: adding share-link access to a resource for people who are NOT
  members of the tenant (often fully unauthenticated) — view, comment, or edit
  by anyone holding the link.
- Use when: designing the share TOKEN itself — entropy/unguessability, expiry,
  revocation, and an optional password/OTP gate.
- Use when: designing the guest SESSION a valid link mints — ephemeral,
  link-scoped, not a membership.
- Use when: an existing share feature uses guessable ids, has no expiry, or
  can't be revoked, and needs a real design.
- Do NOT use when: the subject is MEMBER roles × permissions × resources, or
  impersonation/support access — that is `authorization-matrix-designer`;
  member RBAC (identity → role → permission) is a different model from a
  bearer link, and a member "shared-with" grant is RBAC, not a public link.
- Do NOT use when: the credential is a MACHINE one — API keys, webhook
  signing, partner secrets — that is `api-event-architect`.
- Do NOT use when: the "guest" is really a member with a lightweight role —
  route to `authorization-matrix-designer`; a guest here holds a link, not an
  account.

## Inputs to Inspect

1. Which resources can be shared and at what permission (view / comment /
   edit) — the scope space each link draws from.
2. Whether guests may be fully unauthenticated, or a lightweight identity
   (name/email) is captured — this changes the session and audit design.
3. Existing token/session infrastructure: how tokens are minted, stored,
   verified, and revoked today (guessable ids and no-expiry are findings).
4. What the shared resource is connected to — related records, the owning
   tenant, sibling resources — so the link's blast radius is bounded to the
   one resource, not its neighbourhood.
5. Compliance/PII posture of shareable resources: whether exposing them to
   unauthenticated holders needs a human/compliance decision.
6. Abuse/rate-limit infrastructure available (per-IP, per-token throttling,
   bot defense) for the enumeration/brute-force defenses.

## Workflow

1. **Design the token.** Opaque and high-entropy (unguessable — never a
   sequential or derivable id), carrying no authority of its own (a lookup key
   whose scope lives server-side; if it must carry claims, it is signed and
   scoped). Default-on expiry with a maximum lifetime, and revocation that is
   immediate and checked server-side on every use.
2. **Bind per-link scope.** Each token maps to exactly ONE resource (or an
   explicit small set) and ONE permission level — least privilege. The scope is
   stored server-side keyed by the token, never inferred from the token or read
   from a client parameter. A view link cannot be escalated to edit by changing
   a request.
3. **Design the guest session.** A valid token mints an ephemeral, link-scoped
   session — NOT a tenant membership and NOT a role. It can touch only the
   link's resource at the link's permission and expires with the link. It never
   inherits the sharer's other access.
4. **Add optional gating.** For sensitive shares, a password or OTP on top of
   the link (the link is something-you-have; the password something-you-know).
   Rate-limit the gate and lock out on brute force.
5. **Defend against enumeration and abuse.** Token entropy makes enumeration
   infeasible; rate-limit link access per token and per IP; return ONE uniform
   response for invalid / expired / revoked / never-existed tokens (no oracle
   distinguishing "expired" from "never existed"); watch for scraping; cap link
   creation per user/tenant.
6. **Bound the tenant blast radius.** The guest session's scope IS the leak
   boundary: the link exposes exactly the shared resource and nothing else — no
   navigation to sibling records, no tenant-wide reads. A link that widens
   beyond its resource is the bug this skill exists to prevent.
7. **Specify the audit contract.** Record link creation (who, resource, scope,
   expiry), each access (token, time, IP within privacy limits), gate
   attempts, and revocation — emitted into `audit-log-architect`'s schema.

## Output Format

```
SHARE-LINK ACCESS DESIGN — <product/resource>
Token: <opaque, high-entropy source; carries-no-authority | signed+scoped;
  expiry default + max lifetime; revocation immediate, checked every use>
Per-link scope: <token → one resource(set) + one permission; stored
  server-side; no client-supplied scope; no view→edit escalation>
Guest session: <ephemeral, link-scoped; NOT a membership/role; expires with link>
Optional gating: <password/OTP; rate-limited; lockout on brute force>
Enumeration/abuse defense: <entropy, per-token+IP rate limit, uniform
  invalid/expired/revoked response, creation cap>
Tenant blast radius: <link exposes exactly the resource; no sibling/tenant reach>
Audit: <creation / access / gate attempts / revocation → audit-log schema>
Open questions / risks: <each with risk-if-wrong / who answers>
```

## Validation Checklist

- [ ] Tokens are opaque and high-entropy — enumeration is infeasible, not
      merely inconvenient; no sequential/derivable ids.
- [ ] Every link has an expiry and can be revoked, and revocation is checked
      server-side on every use (not just a hidden UI button).
- [ ] Scope is bound per link to one resource + one permission, stored
      server-side; a view link cannot be escalated to edit.
- [ ] The guest session is ephemeral and link-scoped — it is not a membership,
      inherits no other access, and expires with the link.
- [ ] Invalid / expired / revoked / never-existed tokens return one uniform
      response — no existence oracle.
- [ ] The link cannot reach sibling resources or tenant-wide data; the scope is
      the enforced leak boundary.
- [ ] Optional password/OTP gates are rate-limited with brute-force lockout.
- [ ] Creation, access, gate attempts, and revocation are audited via
      `audit-log-architect`.

## Security Rules

- The token is a bearer credential: whoever holds it is the actor, so it must
  be unguessable, least-privileged, expiring, and revocable — the four
  properties are non-negotiable, not options.
- Scope lives server-side keyed by the token; nothing about what a link can do
  is read from the client or inferred from the token value.
- No existence oracle: the response for a token that never existed and one that
  expired or was revoked is identical.
- The guest session never inherits the sharer's memberships, roles, or reach —
  it is exactly the link's one scope and nothing more.
- Use vetted cryptographic/token primitives (a CSPRNG, established token
  formats); this skill does not design new crypto.

## Gotchas

- Guessable or sequential link ids turn "anyone with the link" into "anyone
  with a for-loop" — enumeration is the classic share-link breach.
- No expiry means links live forever: one leaked link in an email thread or a
  cached URL is permanent access until someone remembers it exists.
- Revocation that only hides the UI button while the token still resolves is
  not revocation — the check must be server-side on every use.
- A view link that flips to edit by changing a client-side permission param is
  a scope-escalation bug; the permission is bound to the token server-side.
- The link becomes a hole into the whole tenant when the guest session can
  navigate from the shared resource to its neighbours — bound the blast radius.
- A password gate with no rate limit is a brute-force target; distinct error
  messages for wrong-password vs no-such-link leak existence.
- Guest access that isn't audited leaves no trail when a link is abused — the
  one actor you can't authenticate is the one you most need to log.

## Stop Conditions

- The "share link" actually needs full member identity, roles, or standing
  access → route to `authorization-matrix-designer`; this is a bearer link, not
  an account.
- The shared resource carries regulated/PII data whose exposure to
  unauthenticated holders needs a human or compliance decision → stop and
  escalate (`human-approval-boundary`, `pii-lifecycle-designer`); do not design
  public exposure of regulated data unilaterally.
- The request is to invent token cryptography or a bespoke signing scheme →
  stop; specify vetted primitives and defer novel crypto to security review.
- Revocation, expiry, or scope cannot actually be enforced server-side in the
  current architecture → surface that gap; a link you cannot revoke or bound is
  not shippable, and saying so is the deliverable.

## Supporting Files

- `evals/evals.json` — behavior cases: the opaque-token share design, the
  guessable-id/no-expiry fix, the view→edit escalation edge, and the
  regulated-data escalation refusal.
- `evals/trigger-evals.json` — discrimination against `authorization-matrix-designer`
  (member RBAC + impersonation) and `api-event-architect` (machine credentials /
  webhook signing).
- No `references/` — the token, scope, and abuse-defense guidance above is the
  complete procedure; detail lives in the produced artifacts.