@vantageos/cloud-identity 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,121 @@
 All notable changes to `@vantageos/cloud-identity` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0]
+
+**Additive — resolution of a PRESENTED, non-master bearer.** The published
+0.5.0 surface covered the master credential (`validateMasterBearer`) and a
+decoder that verifies nothing and says so (`decodeUnverifiedBearer`). Between
+them there was no function taking a presented non-master bearer, hashing it,
+looking the row up and returning a resolved identity or a typed refusal — so a
+consuming product wrote that primitive locally, against an untyped client, with
+the lookup failure swallowed into `null`. That is a second authority answering
+"who is calling". This release is the single one, so the local variant can be
+deleted rather than duplicated.
+
+**Version number.** This entry takes `0.7.0`, not `0.6.0`. An unmerged branch
+already claims `0.6.0` for `resolveTenantIdOrAbsent` (the non-throwing sibling
+of `requireTenantId`); leaving `0.6.0` to it means these two can land in either
+order without either having to be renumbered after review.
+
+### Added
+
+- `validatePresentedBearer(authHeader, deps)` (`src/presented-bearer.ts`) —
+  parses the header, hashes the token to a SHA-256 hex digest, obtains the row
+  through the caller-supplied `deps.lookupBySecretHash(digest)`, re-compares the
+  row's stored digest with `timingSafeEqual`, then honours row shape, revocation
+  and expiry. The package cannot query a datastore, so the read is injected; every
+  decision stays in the package. `deps.now` is an injectable clock.
+  - **The callback receives the DIGEST, never the token**, keeping a usable
+    secret out of a consumer's query and out of its query logs.
+  - **An unknown digest, a revoked row, an expired row, a row of invalid shape
+    and a row whose stored digest does not match all return ONE shared frozen
+    value**, `{ ok: false, error: "mismatch" }` — one object rather than five
+    equal literals, so the branches cannot drift apart by an added field. A
+    prober cannot learn whether a token was ever real. `deps.onRefusal` reports
+    the internal distinction (`PresentedBearerInternalReason`) to the consumer's
+    own logs; a throwing sink cannot change the outcome.
+  - **A lookup that throws is a REFUSAL** (`error: "unavailable"`), deliberately
+    outside the collapsed bucket so a datastore outage can be answered 503
+    rather than reported to every caller as a bad credential. No branch grants
+    anything on a lookup failure.
+  - Header vocabulary is `validateMasterBearer`'s, unchanged: `"missing"`,
+    `"malformed"`, `"mismatch"`. A malformed header costs no datastore read.
+- `requireAgentScopedIdentity(identity)` — the second, mandatory call for a
+  per-agent surface. An organization-wide token (a row with no agent identity)
+  resolves successfully and carries its agent as an EXPLICIT absence
+  (`AgentPresence`, a union that must be narrowed — not a nullable field a
+  caller can fail to check). The per-agent form `AgentScopedIdentity` carries a
+  module-private type brand, so it cannot be constructed outside the package: a
+  handler typed against it is reachable only through this function. Its refusal
+  is distinguishable from a bad credential on purpose — 403, not 401.
+- `sha256Hex(input)` (`src/crypto.ts`) — lower-case hex SHA-256 of a string,
+  exported so the code WRITING a token row derives the digest exactly as the
+  resolver recomputes it.
+- `storedBearerRowSchema` + `StoredBearerRow`, `AgentPresence`,
+  `ResolvedBearerIdentity`, `AgentScopedIdentity`,
+  `ValidatePresentedBearerResult`, `RequireAgentScopedResult`,
+  `PresentedBearerDeps`, `PresentedBearerInternalReason`.
+- Subpath export `@vantageos/cloud-identity/presented-bearer`.
+
+### Changed
+
+- Documentation only: `decodeUnverifiedBearer`'s security banner said the
+  production trust boundary was "not yet exported by this package". For an
+  opaque token it now is, and the banner names it. No behaviour change.
+
+### Unchanged
+
+- **Every existing export keeps its exact behaviour and signature.** The new
+  module is a new file; the only edits to existing sources are one appended
+  function in `src/crypto.ts`, new export lines in `src/index.ts`, and the
+  docstring above. No existing test was edited.
+
+## [0.6.0]
+
+**Additive — typed refusal for reads, and a role assertion.**
+
+### Added
+
+- `resolveTenantIdOrAbsent(source)` (`src/org-guard.ts`): non-throwing sibling
+  of `requireTenantId`. Returns `{ present: true, tenantId }` or a typed
+  `{ present: false, absence: { code: "TENANT_ABSENT", reason } }`. A read that
+  throws crashes a mounted render; a read that returns a bare empty value is
+  byte-identical to "there is nothing". This returns neither.
+- `requireHumanRole(session, required)` and
+  `resolveHumanRoleOrRefusal(session, required)` (`src/human-path.ts`): role
+  assertion on the verified session's `orgRole`, throwing and non-throwing
+  forms. Exact match, no hierarchy; an empty required list admits nobody.
+- Types: `TenantAbsence`, `TenantAbsenceReason`, `TenantResolution`,
+  `RequiredHumanRole`, `RoleRefusal`, `RoleRefusalReason`, `RoleResolution`.
+
+### Fixed
+
+- The Clerk org-role map is now prototype-less (`Object.create(null)`). As a
+  plain object literal it inherited `Object.prototype`, so a presented
+  `orgRole` of `toString`, `constructor`, `valueOf` or `__proto__` did not
+  MISS the lookup — it returned an inherited value, which is truthy, and the
+  resolver handed back a FUNCTION as the role instead of refusing. Any key
+  that is not one of the eight own keys is now `undefined`, so the existing
+  refusal path rejects it. Fixed at the data; no lookup expression and no
+  function body changed, and no list of forbidden names was introduced.
+
+### Unchanged
+
+- `requireTenantId` and `normalizeVerifiedHumanSession` are byte-for-byte
+  unchanged and still throw on every refusal.
+- The tenant key stays opaque: no export takes or returns a slug. That
+  opacity is now pinned on all four served paths (session, bearer,
+  self-host, `role.identity.tenant`), through BOTH the throwing and the
+  non-throwing sibling, with a fixture carrying edge whitespace so that
+  splicing a `.trim()` onto a served id goes RED instead of passing.
+
+### Removed
+
+- `bun.lock`, committed by accident in 0.5.0. `package-lock.json` is the
+  lockfile of record; two lockfiles for two package managers guarantee a
+  silent divergence.
+
 ## [0.5.0]
 
 **Additive — grant-aware scope filter.** Closes the other pole of the

package/README.md

@@ -105,9 +105,72 @@ await resolveTenant({ session: null }); // throws Error("Unauthenticated: no ses
   `{ kind: "bearer", context }` for a machine caller. A missing session, a
   missing organization and an empty organization id are all refusals, never a
   default.
+- `resolveTenantIdOrAbsent(source)` — the NON-throwing sibling of
+  `requireTenantId`, for a public READ. Same `TenantSource` union, same
+  refusal conditions; instead of throwing it returns
+  `{ present: true, tenantId }` or
+  `{ present: false, absence: { code: "TENANT_ABSENT", reason } }`
+  (`TenantAbsence`, `TenantAbsenceReason`, `TenantResolution`). The absence
+  is a non-empty object: it is never `[]`, `{}`, `null` or a zeroed count, so
+  "no organization" and "an organization with nothing in it" cannot collapse
+  into one value. Use `requireTenantId` at a WRITE boundary and
+  `resolveTenantIdOrAbsent` where a throw would crash a mounted render. The
+  tenant id is OPAQUE — returned byte-for-byte, never a slug or display name.
+- `requireHumanRole(session, required)` — asserts the VERIFIED session
+  carries `required` (a `HumanAccountRole` or a list of them, exact match, no
+  hierarchy) and returns the resolved identity; throws otherwise. The role is
+  read from `session.orgRole`, never from an argument. `RequiredHumanRole`
+  is its `required` type.
+- `resolveHumanRoleOrRefusal(session, required)` — the non-throwing form:
+  `{ admitted: true, identity }` or
+  `{ admitted: false, refusal: { code: "ROLE_REFUSED", reason } }`
+  (`RoleResolution`, `RoleRefusal`, `RoleRefusalReason`). `reason` is
+  `role-not-held` for a verified member lacking the role.
 - `getEffectiveTenantId(ctx, args)` — resolves which tenant a request should
   act on when a caller may legitimately act on more than one.
 
+**Resolving a presented bearer token**
+
+- `validatePresentedBearer(authHeader, deps)` — takes the raw
+  `Authorization` header a non-master caller presented, and returns either a
+  resolved identity or a coarse refusal. It hashes the token, asks your
+  `deps.lookupBySecretHash` callback for the row carrying that digest,
+  re-compares the stored digest in constant time, and then checks revocation
+  and expiry. Your callback does one indexed read; every decision stays in the
+  package, so two consumers cannot drift into two different answers to "who is
+  calling".
+  - **Your callback receives the digest, never the token.** A raw secret
+    therefore never reaches your query, your query log or your slow-query log.
+    Use `sha256Hex` to produce the same digest when you WRITE a token row, so
+    the two sides agree.
+  - **An unknown token, a revoked token and an expired token return one
+    identical value** (`{ ok: false, error: "mismatch" }`). Someone probing
+    your endpoint cannot learn from the reply whether a token was ever real.
+    Pass `deps.onRefusal` to receive the distinction
+    (`PresentedBearerInternalReason`) in your own logs, where it belongs.
+  - **A failing lookup refuses.** If your callback throws, the result is
+    `{ ok: false, error: "unavailable" }` — a refusal you can answer with 503
+    instead of 401. There is no branch that grants anything when the lookup
+    fails.
+  - `deps.now` is an injectable clock, so expiry is testable without waiting.
+  - Types: `PresentedBearerDeps`, `StoredBearerRow` (validated at runtime by
+    `storedBearerRowSchema`), `ResolvedBearerIdentity`,
+    `ValidatePresentedBearerResult`.
+- `requireAgentScopedIdentity(identity)` — narrows a resolved identity to a
+  surface that acts as ONE agent, and refuses when the token has no agent.
+  A token can be organization-wide: it names a tenant and no agent. That is a
+  legitimate credential, and it must never be silently widened into whichever
+  agent the surface happened to be about. So the agent is not a nullable field
+  you have to remember to check — `ResolvedBearerIdentity.agent` is an
+  `AgentPresence`, a union you must narrow, and the per-agent form
+  (`AgentScopedIdentity`, with a plain `agentId: string`) can only be obtained
+  from this function. Returns `RequireAgentScopedResult`; its refusal is
+  distinct from a bad credential, because the right answer there is 403, not
+  401.
+- `sha256Hex(input)` — the lower-case hex SHA-256 digest of a string. Exported
+  so that the code storing a token row hashes it exactly the way the resolver
+  will recompute it. Hash once, store the digest, discard the token.
+
 **Row filtering**
 
 - `passesScopeFilter(ctx, row)` — true when this row is visible to this
@@ -228,6 +291,15 @@ Worth reading before you rely on it.
 - **It does not talk to your database.** `scopeFilterList` filters rows you
   have already fetched. If fetching them was itself expensive or unsafe, filter
   earlier, in your query.
+- **It does not issue, rotate or revoke tokens.** `validatePresentedBearer`
+  reads a row you already store and decides whether it may be believed. Minting
+  a token, writing its row, marking it revoked and expiring it are yours; the
+  package only insists that a row it is handed be believed in constant time,
+  and refused identically however it fails.
+- **It does not verify a signed JWT.** The presented-bearer path is for an
+  OPAQUE token — one whose only meaning is the row it matches. If your
+  credential carries its own signed claims, verify that signature with a JWT
+  library first; this package exports no verifier.
 
 ## Upgrading to 0.4.0
 

package/dist/crypto.d.ts

@@ -15,4 +15,16 @@
  * Deno, edge runtimes) and parity with the original Convex implementation.
  */
 export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): Promise<boolean>;
+/**
+ * SHA-256 of a UTF-8 string as a lower-case hex digest.
+ *
+ * Exported because a consumer that STORES a bearer row must produce the digest
+ * the same way the resolver will recompute it. Without this, each consumer
+ * hashes its own way and the mismatch surfaces as "correct token refused".
+ *
+ * @security Hash the token once, store the digest, discard the token. This
+ * function is one-way; it is not a substitute for a comparison — compare
+ * digests with `timingSafeEqual`, never with `===`.
+ */
+export declare function sha256Hex(input: string): Promise<string>;
 //# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CACnC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D"}

package/dist/crypto.js

@@ -29,4 +29,22 @@ export async function timingSafeEqual(a, b) {
     }
     return diff === 0;
 }
+/**
+ * SHA-256 of a UTF-8 string as a lower-case hex digest.
+ *
+ * Exported because a consumer that STORES a bearer row must produce the digest
+ * the same way the resolver will recompute it. Without this, each consumer
+ * hashes its own way and the mismatch surfaces as "correct token refused".
+ *
+ * @security Hash the token once, store the digest, discard the token. This
+ * function is one-way; it is not a substitute for a comparison — compare
+ * digests with `timingSafeEqual`, never with `===`.
+ */
+export async function sha256Hex(input) {
+    const data = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
 //# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,CAAa,EACb,CAAa;IAEb,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACxC,KAAK,EACL,WAAsC,EACtC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;QACF,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAgC,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC"}
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,CAAa,EACb,CAAa;IAEb,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACxC,KAAK,EACL,WAAsC,EACtC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;QACF,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAgC,CAAC,CAAC;QACzE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAa;IAC3C,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACjD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/human-path.d.ts

@@ -92,4 +92,50 @@ export type ResolvedHumanIdentity = {
  * ```
  */
 export declare function normalizeVerifiedHumanSession(session: ClerkSessionLike | null | undefined): ResolvedHumanIdentity;
+/**
+ * Why a caller was not admitted. `role-not-held` is the one that matters: a
+ * verified member of the organization who does not carry the required role.
+ */
+export type RoleRefusalReason = "no-session" | "no-organization" | "no-verified-role" | "role-not-held";
+/** The typed refusal. A non-empty object carrying its own code. */
+export type RoleRefusal = {
+    code: "ROLE_REFUSED";
+    reason: RoleRefusalReason;
+};
+/** Result of `resolveHumanRoleOrRefusal`. Branch on `admitted`. */
+export type RoleResolution = {
+    admitted: true;
+    identity: ResolvedHumanIdentity;
+} | {
+    admitted: false;
+    refusal: RoleRefusal;
+};
+/**
+ * `required` is the POLICY the call site declares; the caller's role is the
+ * CLAIM, and it is read only from `session.orgRole` (which the caller has
+ * already verified upstream — see the @security note on
+ * `normalizeVerifiedHumanSession`). There is no parameter through which a
+ * caller can supply its own role. Matching is EXACT, with no hierarchy:
+ * `owner` does not satisfy `"admin"`; pass `["owner", "admin"]` to admit
+ * either. An empty list admits nobody.
+ */
+export type RequiredHumanRole = HumanAccountRole | readonly HumanAccountRole[];
+/**
+ * THROWING form, for a write boundary. Returns the resolved identity when
+ * the verified session carries one of the `required` roles; throws
+ * otherwise. Malformed sessions throw exactly what
+ * `normalizeVerifiedHumanSession` throws; a well-formed session lacking the
+ * role throws "Role refused: ...".
+ *
+ * Same `@security` precondition as `normalizeVerifiedHumanSession`: this
+ * asserts on a session that is ALREADY verified. It verifies nothing.
+ */
+export declare function requireHumanRole(session: ClerkSessionLike | null | undefined, required: RequiredHumanRole): ResolvedHumanIdentity;
+/**
+ * NON-THROWING form, for a public read. Returns `{ admitted: true, identity }`
+ * or `{ admitted: false, refusal }` where the refusal carries `ROLE_REFUSED`
+ * and a reason. Admits exactly the sessions `requireHumanRole` returns for
+ * and refuses exactly the ones it throws for.
+ */
+export declare function resolveHumanRoleOrRefusal(session: ClerkSessionLike | null | undefined, required: RequiredHumanRole): RoleResolution;
 //# sourceMappingURL=human-path.d.ts.map

package/dist/human-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"human-path.d.ts","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,sBAAsB;;;;;EAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAMF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAoBF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC3C,qBAAqB,CAiCvB"}
+{"version":3,"file":"human-path.d.ts","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,sBAAsB;;;;;EAKjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAMF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAgCF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAC3C,qBAAqB,CAiCvB;AAMD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,CAAC;AAEpB,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,qBAAqB,CAAA;CAAE,GACnD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,gBAAgB,EAAE,CAAC;AAM/E;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC5C,QAAQ,EAAE,iBAAiB,GAC1B,qBAAqB,CAWvB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC5C,QAAQ,EAAE,iBAAiB,GAC1B,cAAc,CAqBhB"}

package/dist/human-path.js

@@ -35,7 +35,17 @@ export const humanAccountRoleSchema = z.enum([
  * listed here is refused rather than silently coerced to a default, per
  * "presented, never inferred from an absence."
  */
-const CLERK_ORG_ROLE_MAP = {
+const CLERK_ORG_ROLE_MAP = Object.assign(
+// PROTOTYPE-LESS on purpose. As a plain object literal this map INHERITED
+// `Object.prototype`, so a lookup of a presented role like `toString`,
+// `constructor` or `__proto__` did not MISS — it returned an inherited
+// value, which is truthy, and the resolver handed back a FUNCTION as the
+// role instead of refusing. With a null prototype, any key that is not one
+// of the eight own keys below is `undefined`, so the existing
+// `if (!mapped) throw` refuses it. The lookup expressions in
+// `normalizeVerifiedHumanSession` and `resolveHumanRoleOrRefusal` are
+// unchanged — this is a fix at the DATA, not a list of forbidden names.
+Object.create(null), {
     "org:owner": "owner",
     owner: "owner",
     "org:admin": "admin",
@@ -44,7 +54,7 @@ const CLERK_ORG_ROLE_MAP = {
     member: "member",
     "org:client": "client",
     client: "client",
-};
+});
 /**
  * @security ⚠️ DECODE/NORMALIZE-ONLY. NOT AUTHENTICATION. NOT VERIFICATION.
  *
@@ -114,4 +124,55 @@ export function normalizeVerifiedHumanSession(session) {
     }
     return { tenant: orgId, subject: userId, role: mapped };
 }
+function requiredList(required) {
+    return typeof required === "string" ? [required] : required;
+}
+/**
+ * THROWING form, for a write boundary. Returns the resolved identity when
+ * the verified session carries one of the `required` roles; throws
+ * otherwise. Malformed sessions throw exactly what
+ * `normalizeVerifiedHumanSession` throws; a well-formed session lacking the
+ * role throws "Role refused: ...".
+ *
+ * Same `@security` precondition as `normalizeVerifiedHumanSession`: this
+ * asserts on a session that is ALREADY verified. It verifies nothing.
+ */
+export function requireHumanRole(session, required) {
+    const identity = normalizeVerifiedHumanSession(session);
+    const allowed = requiredList(required);
+    if (!allowed.includes(identity.role)) {
+        throw new Error(`Role refused: this session is a verified member but does not carry ${allowed.length === 0 ? "any admitted role" : `role ${allowed.join(" or ")}`}.`);
+    }
+    return identity;
+}
+/**
+ * NON-THROWING form, for a public read. Returns `{ admitted: true, identity }`
+ * or `{ admitted: false, refusal }` where the refusal carries `ROLE_REFUSED`
+ * and a reason. Admits exactly the sessions `requireHumanRole` returns for
+ * and refuses exactly the ones it throws for.
+ */
+export function resolveHumanRoleOrRefusal(session, required) {
+    const refuse = (reason) => ({
+        admitted: false,
+        refusal: { code: "ROLE_REFUSED", reason },
+    });
+    if (!session)
+        return refuse("no-session");
+    const { orgId, userId, orgRole } = session;
+    if (typeof orgId !== "string" || orgId.length === 0) {
+        return refuse("no-organization");
+    }
+    if (typeof userId !== "string" || userId.length === 0) {
+        return refuse("no-verified-role");
+    }
+    if (typeof orgRole !== "string" || orgRole.length === 0) {
+        return refuse("no-verified-role");
+    }
+    const role = CLERK_ORG_ROLE_MAP[orgRole];
+    if (!role)
+        return refuse("no-verified-role");
+    if (!requiredList(required).includes(role))
+        return refuse("role-not-held");
+    return { admitted: true, identity: { tenant: orgId, subject: userId, role } };
+}
 //# sourceMappingURL=human-path.js.map

package/dist/human-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"human-path.js","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3C,OAAO;IACP,OAAO;IACP,QAAQ;IACR,QAAQ;CACT,CAAC,CAAC;AA6BH;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAqC;IAC3D,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,OAAO;IACd,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,QAAQ;IACtB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,UAAU,6BAA6B,CAC3C,OAA4C;IAE5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,mCAAmC,OAAO,sBAAsB,MAAM,CAAC,IAAI,CACzE,kBAAkB,CACnB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAChB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"human-path.js","sourceRoot":"","sources":["../src/human-path.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,14 +5,16 @@
  * tenant resolution, membership requirement, row filtering and bearer
  * validation.
  */
-export { timingSafeEqual } from "./crypto.js";
+export { timingSafeEqual, sha256Hex } from "./crypto.js";
 export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWildcardScope, LEGACY_WILDCARD_CTX, type ScopeFilterable, } from "./scope-filter.js";
 export { validateMasterBearer } from "./bearer-validation.js";
 export type { OAuthCtx, ScopeProfile, NamespacePrefix, FromAllowListEntry, ValidateMasterBearerResult, } from "./types.js";
 export { workspaceSchema, workspaceMemberSchema, workspaceRoleSchema, tenantContextSchema, ScopeViolationError, getEffectiveTenantId, decodeUnverifiedBearer, } from "./tenancy-domain.js";
 export type { Workspace, WorkspaceMember, WorkspaceRole, TenantContext, ScopeViolationPayload, BearerPayload, } from "./tenancy-domain.js";
-export { requireTenantId } from "./org-guard.js";
-export type { SessionIdentity, TenantSource, DeploymentMode, } from "./org-guard.js";
-export { humanAccountRoleSchema, normalizeVerifiedHumanSession } from "./human-path.js";
-export type { HumanAccountRole, ClerkSessionLike, ResolvedHumanIdentity, } from "./human-path.js";
+export { requireTenantId, resolveTenantIdOrAbsent } from "./org-guard.js";
+export type { TenantAbsence, TenantAbsenceReason, TenantResolution, SessionIdentity, TenantSource, DeploymentMode, } from "./org-guard.js";
+export { humanAccountRoleSchema, normalizeVerifiedHumanSession, requireHumanRole, resolveHumanRoleOrRefusal, } from "./human-path.js";
+export type { RequiredHumanRole, RoleRefusal, RoleRefusalReason, RoleResolution, HumanAccountRole, ClerkSessionLike, ResolvedHumanIdentity, } from "./human-path.js";
+export { validatePresentedBearer, requireAgentScopedIdentity, storedBearerRowSchema, } from "./presented-bearer.js";
+export type { StoredBearerRow, AgentPresence, ResolvedBearerIdentity, AgentScopedIdentity, ValidatePresentedBearerResult, RequireAgentScopedResult, PresentedBearerDeps, PresentedBearerInternalReason, } from "./presented-bearer.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -5,13 +5,17 @@
  * tenant resolution, membership requirement, row filtering and bearer
  * validation.
  */
-export { timingSafeEqual } from "./crypto.js";
+export { timingSafeEqual, sha256Hex } from "./crypto.js";
 export { passesScopeFilter, scopeFilterList, scopeFilterGet, isMasterScope, isWildcardScope, LEGACY_WILDCARD_CTX, } from "./scope-filter.js";
 export { validateMasterBearer } from "./bearer-validation.js";
 // 0.2.0 — Domain-tenancy layer (additive)
 export { workspaceSchema, workspaceMemberSchema, workspaceRoleSchema, tenantContextSchema, ScopeViolationError, getEffectiveTenantId, decodeUnverifiedBearer, } from "./tenancy-domain.js";
 // Organization-membership guard (unified session + bearer + self-host contract)
-export { requireTenantId } from "./org-guard.js";
+export { requireTenantId, resolveTenantIdOrAbsent } from "./org-guard.js";
 // 0.4.0 — Human-path resolver (Clerk-shaped session -> { tenant, subject, role })
-export { humanAccountRoleSchema, normalizeVerifiedHumanSession } from "./human-path.js";
+export { humanAccountRoleSchema, normalizeVerifiedHumanSession, requireHumanRole, resolveHumanRoleOrRefusal, } from "./human-path.js";
+// Presented-bearer resolution — the opaque-token trust boundary for a
+// NON-MASTER credential. The package's single answer to "who is calling"
+// for a presented bearer; consumers must not keep a local variant.
+export { validatePresentedBearer, requireAgentScopedIdentity, storedBearerRowSchema, } from "./presented-bearer.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAOjD,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAU1E,kFAAkF;AAClF,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAWzB,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/org-guard.d.ts

@@ -92,4 +92,52 @@ export type TenantSource = {
  * organization/workspace information is missing.
  */
 export declare function requireTenantId(source: TenantSource): string;
+/**
+ * Why a caller resolved to no tenant. A closed set, so a consumer can branch
+ * on content.
+ */
+export type TenantAbsenceReason = "no-session" | "no-organization" | "no-workspace" | "no-tenant-configured";
+/**
+ * The typed absence. It is a NON-empty object carrying its own code: it can
+ * never be mistaken for `[]`, `{}`, `null`, `0` or a zeroed aggregate, all of
+ * which are what "an organization with nothing in it" looks like.
+ */
+export type TenantAbsence = {
+    code: "TENANT_ABSENT";
+    reason: TenantAbsenceReason;
+};
+/**
+ * Result of `resolveTenantIdOrAbsent`. Branch on `present`; the two arms
+ * share no field, so a consumer that forgets to branch gets a type error
+ * rather than a silently-empty read.
+ */
+export type TenantResolution = {
+    present: true;
+    tenantId: string;
+} | {
+    present: false;
+    absence: TenantAbsence;
+};
+/**
+ * The tenant id is OPAQUE. It is returned byte-for-byte as presented
+ * (`orgId`, `workspaceId` or the self-host `tenantId`), never trimmed,
+ * lower-cased or otherwise interpreted. This package never receives or
+ * derives a slug or any human-facing name; each product maps its own notion
+ * (an organization id, a workspace id) onto that string.
+ *
+ * NON-THROWING sibling of `requireTenantId`, for a public READ.
+ *
+ * `requireTenantId` throws on every branch, which is right for a WRITE
+ * boundary and wrong for a subscribed read: a throw at a caller with no
+ * organization crashes a mounted render, while a bare empty value is
+ * byte-identical to "there is nothing". This function does neither: it
+ * returns the tenant, or a typed absence that cannot be confused with an
+ * empty result.
+ *
+ * Same `TenantSource` union, same refusal conditions as `requireTenantId` —
+ * every input that makes it throw makes this return `{ present: false }`,
+ * and every input it serves is served identically. Grants nothing that
+ * `requireTenantId` refuses.
+ */
+export declare function resolveTenantIdOrAbsent(source: TenantSource): TenantResolution;
 //# sourceMappingURL=org-guard.d.ts.map

package/dist/org-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"org-guard.d.ts","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+B5D"}
+{"version":3,"file":"org-guard.d.ts","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CA+B5D;AAMD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,iBAAiB,GACjB,cAAc,GACd,sBAAsB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CA4B9E"}

package/dist/org-guard.js

@@ -74,4 +74,52 @@ export function requireTenantId(source) {
     }
     return workspaceId;
 }
+/**
+ * The tenant id is OPAQUE. It is returned byte-for-byte as presented
+ * (`orgId`, `workspaceId` or the self-host `tenantId`), never trimmed,
+ * lower-cased or otherwise interpreted. This package never receives or
+ * derives a slug or any human-facing name; each product maps its own notion
+ * (an organization id, a workspace id) onto that string.
+ *
+ * NON-THROWING sibling of `requireTenantId`, for a public READ.
+ *
+ * `requireTenantId` throws on every branch, which is right for a WRITE
+ * boundary and wrong for a subscribed read: a throw at a caller with no
+ * organization crashes a mounted render, while a bare empty value is
+ * byte-identical to "there is nothing". This function does neither: it
+ * returns the tenant, or a typed absence that cannot be confused with an
+ * empty result.
+ *
+ * Same `TenantSource` union, same refusal conditions as `requireTenantId` —
+ * every input that makes it throw makes this return `{ present: false }`,
+ * and every input it serves is served identically. Grants nothing that
+ * `requireTenantId` refuses.
+ */
+export function resolveTenantIdOrAbsent(source) {
+    const absent = (reason) => ({
+        present: false,
+        absence: { code: "TENANT_ABSENT", reason },
+    });
+    if (source.kind === "session") {
+        if (!source.identity)
+            return absent("no-session");
+        const orgId = source.identity.orgId;
+        if (typeof orgId !== "string" || orgId.length === 0) {
+            return absent("no-organization");
+        }
+        return { present: true, tenantId: orgId };
+    }
+    if (source.kind === "self-host") {
+        const tenantId = source.tenantId;
+        if (typeof tenantId !== "string" || tenantId.length === 0) {
+            return absent("no-tenant-configured");
+        }
+        return { present: true, tenantId };
+    }
+    const workspaceId = source.context?.workspaceId;
+    if (typeof workspaceId !== "string" || workspaceId.length === 0) {
+        return absent("no-workspace");
+    }
+    return { present: true, tenantId: workspaceId };
+}
 //# sourceMappingURL=org-guard.js.map

package/dist/org-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"org-guard.js","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAyCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CACb,gHAAgH,CACjH,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}
+{"version":3,"file":"org-guard.js","sourceRoot":"","sources":["../src/org-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAyCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CACb,gHAAgH,CACjH,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAmCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAoB;IAC1D,MAAM,MAAM,GAAG,CAAC,MAA2B,EAAoB,EAAE,CAAC,CAAC;QACjE,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE;KAC3C,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC;IAChD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AAClD,CAAC"}

package/dist/presented-bearer.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Presented-bearer resolution — the opaque-token trust boundary.
+ * (See package.json "version" for the release this shipped in.)
+ *
+ * Closes the gap between the two credential paths the package already had:
+ *
+ *   - `validateMasterBearer` covers the MASTER credential only (one configured
+ *     secret, no datastore, no identity beyond "it was the master").
+ *   - `decodeUnverifiedBearer` says in its own name that it verifies nothing;
+ *     its payload is attacker-controlled and is not a trust boundary.
+ *
+ * Between them there was no function taking a PRESENTED, NON-MASTER bearer,
+ * hashing it, looking the row up and returning a resolved identity or a typed
+ * refusal. Consumers therefore wrote that primitive locally — a second
+ * authority answering "who is calling", which is exactly what must not exist.
+ * This module is the single one.
+ *
+ * DIVISION OF LABOUR. The package cannot query a datastore, so the row lookup
+ * arrives as a caller-supplied callback. Everything that can be got wrong
+ * stays here: the header parse, the hashing, the constant-time digest compare,
+ * revocation, expiry, row-shape validation, and the SHAPE of the refusal. The
+ * caller supplies one indexed read and nothing else.
+ *
+ * Errors are coarse-grained on purpose — callers should not surface the exact
+ * reason to remote clients beyond a generic 401/403. The vocabulary is
+ * `validateMasterBearer`'s, unchanged: "missing", "malformed", "mismatch".
+ *
+ * @security The callback is invoked with the SHA-256 HEX DIGEST of the
+ * presented token, never the token. A consumer's datastore query, query log
+ * and slow-query log therefore never see a usable secret. The raw token does
+ * not appear in any returned value, any refusal, or any logging callback.
+ */
+import { z } from "zod";
+/**
+ * Shape of the row a consumer's datastore returns for a given digest.
+ *
+ * `agentId` ABSENT (undefined or null) means an ORGANIZATION-WIDE token: it
+ * carries a tenant but no agent identity. Such a row is valid and resolves
+ * successfully; what it may NOT do is stand in for an agent. See
+ * `requireAgentScopedIdentity`.
+ *
+ * `secretHash` is the digest as stored by the consumer. It is re-compared here
+ * against the digest computed from the presented token, in constant time, so a
+ * lookup that performs a loose match (prefix, LIKE, case-folded index) or that
+ * returns the wrong row cannot become an authentication.
+ */
+export declare const storedBearerRowSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    secretHash: z.ZodString;
+    agentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    revoked: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    scopes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export type StoredBearerRow = z.infer<typeof storedBearerRowSchema>;
+/**
+ * The agent, present or explicitly absent. A DISCRIMINATED UNION rather than a
+ * nullable `agentId?: string`, because a nullable field is a duty to remember
+ * and this one was being forgotten: `identity.agent.agentId` does not type-check
+ * until the caller has narrowed on `present`.
+ */
+export type AgentPresence = {
+    present: true;
+    agentId: string;
+} | {
+    present: false;
+    code: "AGENT_ABSENT";
+    reason: "organization-wide-token";
+};
+/**
+ * A resolved, verified caller. Carries the tenant always, and the agent as a
+ * presence-or-absence. Carries NO secret and no digest.
+ */
+export type ResolvedBearerIdentity = {
+    tenantId: string;
+    agent: AgentPresence;
+    scopes: readonly string[];
+};
+/**
+ * Brand for `AgentScopedIdentity`. Declared and NOT exported, so the branded
+ * type cannot be constructed anywhere outside this module: a per-agent surface
+ * that types its parameter as `AgentScopedIdentity` can only be reached through
+ * `requireAgentScopedIdentity`. That is what makes the organization-wide-token
+ * refusal structural rather than a convention a caller may skip.
+ */
+declare const agentScopedBrand: unique symbol;
+/**
+ * A resolved caller that HAS an agent. `agentId` is a plain non-optional
+ * string, so per-agent code needs no narrowing and has nothing to forget.
+ */
+export type AgentScopedIdentity = {
+    readonly [agentScopedBrand]: true;
+    tenantId: string;
+    agentId: string;
+    scopes: readonly string[];
+};
+/**
+ * Result of `validatePresentedBearer`.
+ *
+ *   - `ok: true` → the row was found, its digest matched in constant time, it
+ *     is neither revoked nor expired, and its shape is valid.
+ *   - `error: "missing"` → no Authorization header.
+ *   - `error: "malformed"` → header present but not parseable as
+ *     `Bearer <non-empty-token>`.
+ *   - `error: "mismatch"` → the single, COLLAPSED refusal. An unknown digest,
+ *     a revoked row, an expired row, a row of invalid shape and a row whose
+ *     stored digest does not match all produce this value and nothing else, so
+ *     a prober cannot learn from the response whether a token was ever real.
+ *   - `error: "unavailable"` → the lookup callback itself threw or rejected.
+ *     Deliberately NOT in the collapsed bucket: a caller must be able to
+ *     answer 503 rather than 401 when its datastore is down, and an attacker
+ *     cannot induce this state for one chosen token rather than another, so it
+ *     discloses nothing about any token. It is a REFUSAL like the others — a
+ *     lookup failure never falls through to a grant.
+ */
+export type ValidatePresentedBearerResult = {
+    ok: true;
+    identity: ResolvedBearerIdentity;
+    error?: undefined;
+} | {
+    ok: false;
+    error: "missing" | "malformed" | "mismatch" | "unavailable";
+    identity?: undefined;
+};
+/**
+ * Result of `requireAgentScopedIdentity`. The refusal is distinguishable from
+ * `validatePresentedBearer`'s refusals on purpose: the credential here is
+ * known-good, and the caller owes the remote client a 403 (wrong surface for
+ * this token), not a 401 (bad token).
+ */
+export type RequireAgentScopedResult = {
+    ok: true;
+    identity: AgentScopedIdentity;
+    error?: undefined;
+} | {
+    ok: false;
+    error: "no-agent-on-token";
+    identity?: undefined;
+};
+/**
+ * Why a refusal happened, for the consumer's own observability. Reported
+ * through `deps.onRefusal`; NEVER present in a returned value, because a
+ * returned distinction is a returned disclosure.
+ *
+ * @security Carries no token, no digest and no row. Only a reason word.
+ */
+export type PresentedBearerInternalReason = "no-header" | "malformed-header" | "unknown-token" | "revoked-token" | "expired-token" | "row-shape-invalid" | "stored-digest-mismatch" | "lookup-failed";
+export type PresentedBearerDeps = {
+    /**
+     * Indexed read of one row by the SHA-256 HEX DIGEST of the presented token.
+     * Returns the row, or null/undefined when no row carries that digest.
+     *
+     * @security The argument is a digest, never the token. Do not log it, and do
+     * not widen this to accept a raw secret.
+     */
+    lookupBySecretHash: (sha256HexDigest: string) => Promise<StoredBearerRow | null | undefined>;
+    /** Injectable clock. Never `Date.now()` inline, so expiry is testable. */
+    now?: () => number;
+    /** Observability sink for the collapsed refusals. Must not throw; if it does, the throw is swallowed and the refusal stands. */
+    onRefusal?: (reason: PresentedBearerInternalReason) => void;
+};
+/**
+ * Resolve an `Authorization: Bearer <token>` header presented by a NON-MASTER
+ * caller into a verified identity, or into a typed refusal.
+ *
+ * Order of operations, and why:
+ *   1. Parse the header. A missing or malformed header is refused WITHOUT
+ *      calling the lookup, so a garbage request costs no datastore read.
+ *   2. Hash the token to a SHA-256 hex digest. The raw token goes no further.
+ *   3. Look the row up BY THAT DIGEST.
+ *   4. Re-compare the row's stored digest against the computed one with
+ *      `timingSafeEqual` — never `!==` on a secret or a digest.
+ *   5. Validate the row's shape, then revocation, then expiry.
+ *   6. Resolve the tenant, and the agent as a presence or an explicit absence.
+ *
+ * Steps 3–5 all refuse with the SAME frozen value. A right is never granted by
+ * absence or by failure: there is no branch that returns `ok: true` without
+ * having passed every check above.
+ *
+ * @example
+ * ```ts
+ * const result = await validatePresentedBearer(req.headers.get("authorization"), {
+ *   lookupBySecretHash: (digest) => db.tokens.byDigest(digest),
+ * });
+ * if (!result.ok) return respond(result.error === "unavailable" ? 503 : 401);
+ * const tenantId = result.identity.tenantId;
+ * ```
+ */
+export declare function validatePresentedBearer(authHeader: string | null | undefined, deps: PresentedBearerDeps): Promise<ValidatePresentedBearerResult>;
+/**
+ * Narrow a resolved identity to a PER-AGENT surface, refusing when the token
+ * carries no agent.
+ *
+ * An organization-wide token is a legitimate credential that is simply not an
+ * agent; treating it as one would silently widen it into whichever agent the
+ * surface happened to be about. So this is a second, mandatory call, and its
+ * output type is branded: a per-agent handler declares `AgentScopedIdentity`
+ * and the only way to obtain one is here.
+ *
+ * Grants nothing on its own — it can only ever narrow an identity
+ * `validatePresentedBearer` already resolved.
+ */
+export declare function requireAgentScopedIdentity(identity: ResolvedBearerIdentity): RequireAgentScopedResult;
+export {};
+//# sourceMappingURL=presented-bearer.d.ts.map

package/dist/presented-bearer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presented-bearer.d.ts","sourceRoot":"","sources":["../src/presented-bearer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;;;;iBAOhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAEhF;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;;GAMG;AACH,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAMF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,sBAAsB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACjE;IACE,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IAC5D,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEN;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GAC9D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAMpE;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GACrC,WAAW,GACX,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,wBAAwB,GACxB,eAAe,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;OAMG;IACH,kBAAkB,EAAE,CAClB,eAAe,EAAE,MAAM,KACpB,OAAO,CAAC,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjD,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gIAAgI;IAChI,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,6BAA6B,KAAK,IAAI,CAAC;CAC7D,CAAC;AAyDF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,6BAA6B,CAAC,CAkFxC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,sBAAsB,GAC/B,wBAAwB,CAY1B"}

package/dist/presented-bearer.js

@@ -0,0 +1,226 @@
+/**
+ * Presented-bearer resolution — the opaque-token trust boundary.
+ * (See package.json "version" for the release this shipped in.)
+ *
+ * Closes the gap between the two credential paths the package already had:
+ *
+ *   - `validateMasterBearer` covers the MASTER credential only (one configured
+ *     secret, no datastore, no identity beyond "it was the master").
+ *   - `decodeUnverifiedBearer` says in its own name that it verifies nothing;
+ *     its payload is attacker-controlled and is not a trust boundary.
+ *
+ * Between them there was no function taking a PRESENTED, NON-MASTER bearer,
+ * hashing it, looking the row up and returning a resolved identity or a typed
+ * refusal. Consumers therefore wrote that primitive locally — a second
+ * authority answering "who is calling", which is exactly what must not exist.
+ * This module is the single one.
+ *
+ * DIVISION OF LABOUR. The package cannot query a datastore, so the row lookup
+ * arrives as a caller-supplied callback. Everything that can be got wrong
+ * stays here: the header parse, the hashing, the constant-time digest compare,
+ * revocation, expiry, row-shape validation, and the SHAPE of the refusal. The
+ * caller supplies one indexed read and nothing else.
+ *
+ * Errors are coarse-grained on purpose — callers should not surface the exact
+ * reason to remote clients beyond a generic 401/403. The vocabulary is
+ * `validateMasterBearer`'s, unchanged: "missing", "malformed", "mismatch".
+ *
+ * @security The callback is invoked with the SHA-256 HEX DIGEST of the
+ * presented token, never the token. A consumer's datastore query, query log
+ * and slow-query log therefore never see a usable secret. The raw token does
+ * not appear in any returned value, any refusal, or any logging callback.
+ */
+import { z } from "zod";
+import { sha256Hex, timingSafeEqual } from "./crypto.js";
+const BEARER_PREFIX_LOWER = "bearer ";
+// ---------------------------------------------------------------------------
+// The stored row
+// ---------------------------------------------------------------------------
+/**
+ * Shape of the row a consumer's datastore returns for a given digest.
+ *
+ * `agentId` ABSENT (undefined or null) means an ORGANIZATION-WIDE token: it
+ * carries a tenant but no agent identity. Such a row is valid and resolves
+ * successfully; what it may NOT do is stand in for an agent. See
+ * `requireAgentScopedIdentity`.
+ *
+ * `secretHash` is the digest as stored by the consumer. It is re-compared here
+ * against the digest computed from the presented token, in constant time, so a
+ * lookup that performs a loose match (prefix, LIKE, case-folded index) or that
+ * returns the wrong row cannot become an authentication.
+ */
+export const storedBearerRowSchema = z.object({
+    tenantId: z.string().min(1),
+    secretHash: z.string().min(1),
+    agentId: z.string().min(1).nullish(),
+    revoked: z.boolean().nullish(),
+    expiresAt: z.number().nullish(),
+    scopes: z.array(z.string()).nullish(),
+});
+// ---------------------------------------------------------------------------
+// The refusals, as shared frozen singletons
+// ---------------------------------------------------------------------------
+const MISSING = Object.freeze({
+    ok: false,
+    error: "missing",
+});
+const MALFORMED = Object.freeze({
+    ok: false,
+    error: "malformed",
+});
+const UNAVAILABLE = Object.freeze({
+    ok: false,
+    error: "unavailable",
+});
+/**
+ * THE collapsed refusal. One frozen value, shared by every branch that must be
+ * externally indistinguishable — unknown digest, revoked, expired, invalid row
+ * shape, stored-digest mismatch. Not five literals that happen to be equal
+ * today: one object, so the branches cannot drift apart by an added field.
+ */
+const COLLAPSED_REFUSAL = Object.freeze({
+    ok: false,
+    error: "mismatch",
+});
+function report(deps, reason) {
+    const sink = deps.onRefusal;
+    if (typeof sink !== "function")
+        return;
+    try {
+        sink(reason);
+    }
+    catch {
+        // A failing logger must never change an authorization outcome.
+    }
+}
+function collapse(deps, reason) {
+    report(deps, reason);
+    return COLLAPSED_REFUSAL;
+}
+// ---------------------------------------------------------------------------
+// validatePresentedBearer
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an `Authorization: Bearer <token>` header presented by a NON-MASTER
+ * caller into a verified identity, or into a typed refusal.
+ *
+ * Order of operations, and why:
+ *   1. Parse the header. A missing or malformed header is refused WITHOUT
+ *      calling the lookup, so a garbage request costs no datastore read.
+ *   2. Hash the token to a SHA-256 hex digest. The raw token goes no further.
+ *   3. Look the row up BY THAT DIGEST.
+ *   4. Re-compare the row's stored digest against the computed one with
+ *      `timingSafeEqual` — never `!==` on a secret or a digest.
+ *   5. Validate the row's shape, then revocation, then expiry.
+ *   6. Resolve the tenant, and the agent as a presence or an explicit absence.
+ *
+ * Steps 3–5 all refuse with the SAME frozen value. A right is never granted by
+ * absence or by failure: there is no branch that returns `ok: true` without
+ * having passed every check above.
+ *
+ * @example
+ * ```ts
+ * const result = await validatePresentedBearer(req.headers.get("authorization"), {
+ *   lookupBySecretHash: (digest) => db.tokens.byDigest(digest),
+ * });
+ * if (!result.ok) return respond(result.error === "unavailable" ? 503 : 401);
+ * const tenantId = result.identity.tenantId;
+ * ```
+ */
+export async function validatePresentedBearer(authHeader, deps) {
+    if (typeof deps?.lookupBySecretHash !== "function") {
+        // A programming error in the consumer, not a claim about any caller: it
+        // must not be reported as a credential refusal.
+        throw new TypeError("validatePresentedBearer: deps.lookupBySecretHash must be a function.");
+    }
+    if (authHeader === undefined || authHeader === null || authHeader === "") {
+        report(deps, "no-header");
+        return MISSING;
+    }
+    // Case-insensitive scheme match without lower-casing the token bytes
+    // (RFC 7235 §2.1), identical to `validateMasterBearer`.
+    const lower = authHeader.toLowerCase();
+    if (!lower.startsWith(BEARER_PREFIX_LOWER)) {
+        report(deps, "malformed-header");
+        return MALFORMED;
+    }
+    const token = authHeader.slice(BEARER_PREFIX_LOWER.length).trim();
+    if (token.length === 0) {
+        report(deps, "malformed-header");
+        return MALFORMED;
+    }
+    const presentedDigest = await sha256Hex(token);
+    let row;
+    try {
+        row = await deps.lookupBySecretHash(presentedDigest);
+    }
+    catch {
+        report(deps, "lookup-failed");
+        return UNAVAILABLE;
+    }
+    if (row === null || row === undefined) {
+        return collapse(deps, "unknown-token");
+    }
+    const parsed = storedBearerRowSchema.safeParse(row);
+    if (!parsed.success) {
+        return collapse(deps, "row-shape-invalid");
+    }
+    const stored = parsed.data;
+    const encoder = new TextEncoder();
+    const digestsMatch = await timingSafeEqual(encoder.encode(stored.secretHash.toLowerCase()), encoder.encode(presentedDigest));
+    if (!digestsMatch) {
+        return collapse(deps, "stored-digest-mismatch");
+    }
+    if (stored.revoked === true) {
+        return collapse(deps, "revoked-token");
+    }
+    const nowMs = deps.now ? deps.now() : Date.now();
+    if (typeof stored.expiresAt === "number" && stored.expiresAt <= nowMs) {
+        return collapse(deps, "expired-token");
+    }
+    const agent = typeof stored.agentId === "string" && stored.agentId.length > 0
+        ? { present: true, agentId: stored.agentId }
+        : {
+            present: false,
+            code: "AGENT_ABSENT",
+            reason: "organization-wide-token",
+        };
+    return {
+        ok: true,
+        identity: {
+            tenantId: stored.tenantId,
+            agent,
+            scopes: stored.scopes ?? [],
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// requireAgentScopedIdentity
+// ---------------------------------------------------------------------------
+/**
+ * Narrow a resolved identity to a PER-AGENT surface, refusing when the token
+ * carries no agent.
+ *
+ * An organization-wide token is a legitimate credential that is simply not an
+ * agent; treating it as one would silently widen it into whichever agent the
+ * surface happened to be about. So this is a second, mandatory call, and its
+ * output type is branded: a per-agent handler declares `AgentScopedIdentity`
+ * and the only way to obtain one is here.
+ *
+ * Grants nothing on its own — it can only ever narrow an identity
+ * `validatePresentedBearer` already resolved.
+ */
+export function requireAgentScopedIdentity(identity) {
+    if (!identity.agent.present) {
+        return { ok: false, error: "no-agent-on-token" };
+    }
+    const scoped = {
+        tenantId: identity.tenantId,
+        agentId: identity.agent.agentId,
+        scopes: identity.scopes,
+        // The brand exists only in the type system; there is no runtime field to
+        // forge, and no value to construct outside this module.
+    };
+    return { ok: true, identity: scoped };
+}
+//# sourceMappingURL=presented-bearer.js.map

package/dist/presented-bearer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presented-bearer.js","sourceRoot":"","sources":["../src/presented-bearer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAEtC,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE;IACpC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAC/B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;CACtC,CAAC,CAAC;AA+HH,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAE9E,MAAM,OAAO,GAAkC,MAAM,CAAC,MAAM,CAAC;IAC3D,EAAE,EAAE,KAAc;IAClB,KAAK,EAAE,SAAkB;CAC1B,CAAC,CAAC;AAEH,MAAM,SAAS,GAAkC,MAAM,CAAC,MAAM,CAAC;IAC7D,EAAE,EAAE,KAAc;IAClB,KAAK,EAAE,WAAoB;CAC5B,CAAC,CAAC;AAEH,MAAM,WAAW,GAAkC,MAAM,CAAC,MAAM,CAAC;IAC/D,EAAE,EAAE,KAAc;IAClB,KAAK,EAAE,aAAsB;CAC9B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,iBAAiB,GAAkC,MAAM,CAAC,MAAM,CAAC;IACrE,EAAE,EAAE,KAAc;IAClB,KAAK,EAAE,UAAmB;CAC3B,CAAC,CAAC;AAEH,SAAS,MAAM,CACb,IAAyB,EACzB,MAAqC;IAErC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,UAAU;QAAE,OAAO;IACvC,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED,SAAS,QAAQ,CACf,IAAyB,EACzB,MAAqC;IAErC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrB,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAAqC,EACrC,IAAyB;IAEzB,IAAI,OAAO,IAAI,EAAE,kBAAkB,KAAK,UAAU,EAAE,CAAC;QACnD,wEAAwE;QACxE,gDAAgD;QAChD,MAAM,IAAI,SAAS,CACjB,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QACzE,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,qEAAqE;IACrE,wDAAwD;IACxD,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAC3C,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,eAAe,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IAE/C,IAAI,GAAuC,CAAC;IAC5C,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QAC9B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,MAAM,GAAG,qBAAqB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IAE3B,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,MAAM,eAAe,CACxC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,EAC/C,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAChC,CAAC;IACF,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACjD,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,IAAI,KAAK,EAAE,CAAC;QACtE,OAAO,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,KAAK,GACT,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC7D,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;QAC5C,CAAC,CAAC;YACE,OAAO,EAAE,KAAK;YACd,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,yBAAyB;SAClC,CAAC;IAER,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE;YACR,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK;YACL,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;SAC5B;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAgC;IAEhC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,MAAM,GAAG;QACb,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO;QAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,yEAAyE;QACzE,wDAAwD;KAClC,CAAC;IACzB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/tenancy-domain.d.ts

@@ -105,9 +105,12 @@ export declare function getEffectiveTenantId(ctx: TenantContext, args: {
  *   - decoder for a bearer that was ALREADY verified by an upstream signed-JWT
  *     middleware (the production trust boundary)
  *
- * For the production trust boundary, callers MUST substitute a signed JWT
- * verifier (not yet exported by this package) or an opaque-token lookup
- * against a Convex tenancy table.
+ * For the production trust boundary on an OPAQUE token, callers MUST use
+ * `validatePresentedBearer` (see `./presented-bearer.ts`), which hashes the
+ * presented token, looks the row up by digest through a caller-supplied read,
+ * re-compares the stored digest in constant time, and honours revocation and
+ * expiry. For a SIGNED JWT, callers must substitute a signature verifier; this
+ * package does not export one.
  *
  * Renamed from `resolveBearer` (0.2.0 pre-release) to make the lack of
  * verification impossible to miss at the call-site.

package/dist/tenancy-domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tenancy-domain.d.ts","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,mBAAmB;;;;EAAwC,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,eAAe;;;;;iBAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,mBAAmB;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;IAC3C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;gBAE5B,OAAO,EAAE,qBAAqB;CAS3C;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CASR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,QAAA,MAAM,mBAAmB;;;;;;;;iBAIvB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC,CAmBxB"}
+{"version":3,"file":"tenancy-domain.d.ts","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,mBAAmB;;;;EAAwC,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,eAAe;;;;;iBAK1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAMxD,eAAO,MAAM,qBAAqB;;;;;;;;;iBAKhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAMpE,eAAO,MAAM,mBAAmB;;;;;;;;iBAI9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,MAAM,WAAW,qBAAqB;IACpC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAU;IAC3C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;gBAE5B,OAAO,EAAE,qBAAqB;CAS3C;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5B,MAAM,CASR;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,QAAA,MAAM,mBAAmB;;;;;;;;iBAIvB,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,CAAC,CAmBxB"}

package/dist/tenancy-domain.js

@@ -115,9 +115,12 @@ export function getEffectiveTenantId(ctx, args) {
  *   - decoder for a bearer that was ALREADY verified by an upstream signed-JWT
  *     middleware (the production trust boundary)
  *
- * For the production trust boundary, callers MUST substitute a signed JWT
- * verifier (not yet exported by this package) or an opaque-token lookup
- * against a Convex tenancy table.
+ * For the production trust boundary on an OPAQUE token, callers MUST use
+ * `validatePresentedBearer` (see `./presented-bearer.ts`), which hashes the
+ * presented token, looks the row up by digest through a caller-supplied read,
+ * re-compares the stored digest in constant time, and honours revocation and
+ * expiry. For a SIGNED JWT, callers must substitute a signature verifier; this
+ * package does not export one.
  *
  * Renamed from `resolveBearer` (0.2.0 pre-release) to make the lack of
  * verification impossible to miss at the call-site.

package/dist/tenancy-domain.js.map

@@ -1 +1 @@
-{"version":3,"file":"tenancy-domain.js","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tenancy-domain.js","sourceRoot":"","sources":["../src/tenancy-domain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGzE,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAGH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,EAAE,mBAAmB;IACzB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC;AAGH,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACpC,CAAC,CAAC;AAaH;;;;;;GAMG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,iBAA0B,CAAC;IAClC,OAAO,CAAwB;IAExC,YAAY,OAA8B;QACxC,KAAK,CACH,sCAAsC,OAAO,CAAC,iBAAiB,oCAAoC,OAAO,CAAC,eAAe,OAAO,OAAO,CAAC,MAAM,EAAE,CAClJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,kFAAkF;QAClF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAkB,EAClB,IAA6B;IAE7B,IAAI,IAAI,CAAC,WAAW,KAAK,GAAG,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,IAAI,mBAAmB,CAAC;YAC5B,iBAAiB,EAAE,IAAI,CAAC,WAAW;YACnC,eAAe,EAAE,GAAG,CAAC,WAAW;YAChC,MAAM,EAAE,qEAAqE;SAC9E,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC;AACzB,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,mBAAmB,CAAC;CACpC,CAAC,CAAC;AAIH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,KAAa;IAEb,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,OAAO,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,10 @@
     "./human-path": {
       "types": "./dist/human-path.d.ts",
       "import": "./dist/human-path.js"
+    },
+    "./presented-bearer": {
+      "types": "./dist/presented-bearer.d.ts",
+      "import": "./dist/presented-bearer.js"
     }
   },
   "files": [