@vantageos/cloud-identity 0.13.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,135 @@
 All notable changes to `@vantageos/cloud-identity` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- `verifyMcpAccessToken` now validates `audience` as an absolute URL with no
+  fragment (RFC 8707 section 2), with the same validator as the `resource` of
+  `buildProtectedResourceMetadata`. A whitespace-only, non-URL or
+  fragment-bearing audience throws the config error instead of being accepted.
+
+## [0.16.0]
+
+**Additive: an organisation is its permanent ID (`./org-by-id`).** A consumer
+used to keep its own copy of "which org is this credential", "are these two
+rows one org", "which org is the operator" and "what is this slug's org ID".
+Those decisions are now the package's, keyed on IDs, refusing by default. No
+existing function changes behaviour for an existing input.
+
+### Added
+
+- `resolveOrgFromClaim(claims, lookups, { door? })`: a verified
+  credential's `org_id` claim to the org's mapping row (roster, scopes, kind).
+- `sameOrg`, `isFleetStamp`, `sameTenantStamp`: comparisons over `OrgRef`
+  (`{ id?, label? }`). Unstamped is never a match.
+- `findOperatorOrg(lookups, { cap? })`: `one | none | many | overCap | unreadable`.
+- `resolveOrgIdForLabelBackfillOnly(label, lookups)`: label to permanent ID,
+  or a typed `ORG_ID_ABSENT` absence. For the one-off backfill only; it must
+  never be called on a request path, and the name says so. (Developed as
+  `resolveOrgIdForLabel`; that name was never published.)
+- `orgMappingRowSchema` and the types `OrgRef`, `OrgMappingRow`,
+  `OrgMappingLookups`, `ResolvedOrg`, `ResolveOrgFromClaimOptions`,
+  `ResolveOrgFromClaimResult`, `OrgIdAbsence`, `OrgIdAbsenceReason`,
+  `OrgIdResolution`, `OperatorOrgLookups`, `FindOperatorOrgOptions`,
+  `OperatorOrgResult`.
+- New `IdentityRefusalReason` values: `org-mapping-lookup-failed`,
+  `org-mapping-not-found`, `org-mapping-record-invalid`.
+
+### No label resolution
+
+An organisation is never resolved from its label on a request path, and no
+option turns that on. A transitional `labelFallback` option was developed and
+removed before publication: `sameOrg`, `isFleetStamp`, `sameTenantStamp` and
+`resolveOrgFromClaim` compare and select by org ID only, a label-only input
+refuses, and the `org-id-contradicts-label` reason and the `source` field of
+`ResolvedOrg` went with it. The label adapter is read only by
+`resolveOrgIdForLabelBackfillOnly`.
+
+## [0.15.0]
+
+**Additive: resource-server primitives (`./resource-server`).** No existing
+function changes behaviour for an existing input. This is the identity layer an
+MCP server needs as an OAuth 2.1 protected resource, so a separate
+resource-server package is no longer needed.
+
+### Added
+
+- `buildProtectedResourceMetadata(config)`: the RFC 9728 document served at
+  `/.well-known/oauth-protected-resource` (`resource`, `authorization_servers`,
+  `bearer_methods_supported`, optional `scopes_supported`, `resource_name`,
+  `resource_documentation`). Throws on a relative or fragment-bearing resource,
+  an empty or relative authorization server list, or empty bearer methods.
+- `unauthorizedChallenge(config)`: the `401` status and a `WWW-Authenticate:
+  Bearer` value that always carries `resource_metadata` (RFC 9728 section 5.1),
+  with optional `error`, `error_description` and `scope` (RFC 6750). Values are
+  quoted and escaped; a line break throws.
+- `deriveClerkDiscoveryUrls(issuer)`: the OIDC discovery and JWKS URLs of an
+  `https` issuer.
+- `verifyMcpAccessToken(authorization, config, nowMs?)`: reads the `Authorization`
+  header and verifies the token for this resource by delegating to
+  `verifyClerkSessionToken` (RS256 only; signature, `iss`, `aud`, `exp`, `nbf`),
+  with the audience mandatory. Returns the verified session, or a typed
+  `CREDENTIAL_REFUSED` refusal with the `401` envelope (`bearer-missing` and
+  `bearer-malformed` answer `invalid_request`; `token-invalid` answers
+  `invalid_token`), or `503` with no challenge when the key set is unreachable
+  (`jwks-unavailable`). A missing issuer or audience throws.
+- Types `ProtectedResourceMetadataConfig`, `ProtectedResourceMetadata`,
+  `UnauthorizedChallengeConfig`, `UnauthorizedChallenge`, `ClerkDiscoveryUrls`,
+  `McpResourceServerConfig`, `VerifyMcpAccessTokenResult`.
+- `IdentityRefusalReason` gains `bearer-missing`, `bearer-malformed`,
+  `token-invalid`, `jwks-unavailable`.
+
+## [0.14.0]
+
+**Additive: who may address whom, which rows a caller may see, and a caller's
+standing, decided by agent ID only (`./principal-by-id`).** No existing function changes behaviour for an existing
+input.
+
+### Added
+
+- `assertRecipientAddressable(sender, recipient, lookups, { door? })` (CI-2):
+  decides, by agent ID only, whether a sender may address a recipient,
+  across organisations included. Admits same organisation; client to operator
+  when the recipient's ID is on the sender organisation's roster; operator to
+  client when the sender's ID is on the recipient organisation's roster.
+  `lookups` is `{ orgKindOf, rosterOf }`. Everything else refuses with a typed
+  `RBAC_DENIED` naming the door: client to client, a missing sender or
+  recipient, a sender that is not an agent, an unresolvable roster. The roster
+  check reuses `assertPrincipalListed`. Types `RecipientIds`,
+  `RecipientLookups`, `AssertRecipientAddressableOptions`,
+  `AssertRecipientAddressableResult`.
+- `resolveCallerStanding(credential, lookups, { adminRoles, door? })` (CI-4):
+  names a caller's standing as `anonymous` (with the typed refusal), `pre-org`
+  (a verified session with no organisation, via the new
+  `{ kind: "person-no-org", personId }` credential), `member`, `admin` or
+  `fleet`. Built on `resolveActingPrincipal` and `assertOrgAdmin`; the only
+  case the existing primitives could not say was `pre-org`, which they refuse
+  like a garbled credential. Types `CallerCredential`,
+  `AssertCallerStandingOptions`, `CallerStanding`.
+- `filterTargetsBelongingTo(principal, rows, lookups, opts?)` (CI-3): the
+  ID-keyed row filter that replaces the name-keyed `scopeFilterList`. Async;
+  returns `{ ok: true, rows }` or `{ ok: false, refusal }`. Each row is kept
+  exactly when `assertTargetBelongsTo` admits it (same `lookups` and options,
+  including `door`, `ownerOnly`, `fleetCrossOrg`); that function is reused, not
+  re-derived. The principal is proved first: an absent or unresolved principal
+  is a refusal naming the door, even for an empty list, never an empty
+  success. A resolved principal whose rows all belong elsewhere gets
+  `{ ok: true, rows: [] }`. Rows of other organisations, unstamped rows and a
+  same-NAME row of another organisation are dropped. A lookup failure on any
+  row refuses the whole call, never a silent drop. `fleetCrossOrg: true` from a
+  principal that is not `kind: "fleet"` is refused `reserved-fleet-scope` for
+  any list. Input order is kept. Type
+  `FilterTargetsResult`.
+
+### Deprecated
+
+- `scopeFilterList`, `scopeFilterGet`, `passesScopeFilter` and the name-keyed
+  `OAuthCtx.fromAllowList` field now point to `filterTargetsBelongingTo` in
+  their TSDoc. Behaviour is unchanged; they are removed when the consumer
+  migrates.
+
 ## [0.13.0]
 
 **Additive: admission by membership of a stored list, by agent ID only

package/README.md

@@ -183,7 +183,7 @@ await resolveTenant({ session: null }); // throws Error("Unauthenticated: no ses
   unrestricted access. Useful for skipping filtering you know is pointless;
   never as a substitute for it.
 
-**Deprecated since 0.11.0: `passesScopeFilter`, `scopeFilterGet` and
+**Deprecated since 0.11.0 (pointing to `filterTargetsBelongingTo` since 0.14.0): `passesScopeFilter`, `scopeFilterGet` and
 `scopeFilterList`.** All three (the last two through the first) admit a row
 when its `createdBy` NAME appears in the caller's `fromAllowList`, so a name
 selects the row, which backend standard R-53 clause 1 forbids. For a target
@@ -720,6 +720,52 @@ const listed = assertPrincipalListed(who.principal, { orgId: row.orgId, principa
 if (!listed.ok) throw toHttpError(listed.refusal);
 ```
 
+**`assertRecipientAddressable(sender, recipient, lookups, opts)`** (`./principal-by-id`, 0.14.0)
+
+Async. Returns `{ ok: true }` or `{ ok: false, refusal }`. `recipient` is
+`{ agentId, orgId }`; `lookups` is `{ orgKindOf, rosterOf }` where
+`rosterOf(orgId)` returns the stored `{ orgId, principalIds }` roster of that
+client organisation; `opts` is `{ door? }`. Decided by agent ID only:
+
+- same organisation: admitted;
+- client sender to operator recipient: the recipient's ID must be on the
+  SENDER organisation's roster;
+- operator sender to client recipient: the sender's ID must be on the
+  RECIPIENT organisation's roster;
+- client to client across organisations, a missing sender or recipient, a
+  sender that is not an agent, an unknown organisation kind and an
+  unresolvable roster all refuse. A name never matches. Types: `RecipientIds`,
+`RecipientLookups`, `AssertRecipientAddressableOptions`,
+`AssertRecipientAddressableResult`.
+
+```js
+const may = await assertRecipientAddressable(who.principal, { agentId: to.id, orgId: to.orgId }, {
+  orgKindOf, rosterOf,
+}, { door: "send_message" });
+if (!may.ok) throw toHttpError(may.refusal);
+```
+
+**`filterTargetsBelongingTo(principal, rows, lookups, opts)`** (`./principal-by-id`, 0.14.0)
+
+Async. The ID-keyed replacement for `scopeFilterList`. Returns
+`{ ok: true, rows }` (the rows `assertTargetBelongsTo` admits, in input order)
+or `{ ok: false, refusal }`. `lookups` and `opts` are those of
+`assertTargetBelongsTo`. Type: `FilterTargetsResult`.
+
+- an absent or unresolved principal is a refusal naming the door, even for an
+  empty list; it is never `{ ok: true, rows: [] }`;
+- a resolved principal whose rows all belong elsewhere gets
+  `{ ok: true, rows: [] }`, so a refusal is distinguishable from an absence;
+- rows of other organisations, unstamped rows and a same-NAME row of another
+  organisation are dropped; a name never decides;
+- a lookup failure is a refusal of the whole call, never a silent drop.
+
+```js
+const out = await filterTargetsBelongingTo(who.principal, rows, { orgKindOf }, { door: "tasks:list" });
+if (!out.ok) throw toHttpError(out.refusal);
+return out.rows;
+```
+
 **The fleet is the operator organisation.** The fleet is not a reserved ID: it
 is the organisation your `orgKindOf` adapter reports as `"operator"` (for
 example the organisation whose mapping row carries `orgKind: "operator"`),
@@ -768,6 +814,145 @@ left in the tables the door reads, then switch the door.
 takes a name as an identity input, and a test reads the exported signatures to
 keep it that way.
 
+### A caller's standing (0.14.0)
+
+`resolveCallerStanding(credential, lookups, { adminRoles, door? })` names which
+of the four callers is asking. It is built on `resolveActingPrincipal` and
+`assertOrgAdmin`; it is not a second path.
+
+| Credential (verified by you) | Standing |
+|---|---|
+| none, garbled, unknown or inactive principal | `anonymous`, with the typed `refusal` |
+| `{ kind: "person-no-org", personId }` | `pre-org` (signed in, no organisation) |
+| person or agent, or a non-operator service account, without the admin role | `member`, with `principal` |
+| person whose `verifiedOrgRole` is in `adminRoles` | `admin`, with `principal` |
+| service account of the operator organisation (`orgKindOf` is `"operator"`) | `fleet`, with `principal` |
+
+Types: `CallerCredential`, `AssertCallerStandingOptions`, `CallerStanding`.
+
+- A master token reaches `fleet` by your mapping it to the operator service
+  account: `validateMasterBearer` proves the secret, then you pass
+  `{ kind: "service", serviceAccountId }`. The package never mints a fleet
+  credential from a bearer.
+- A Clerk session reaches the function through `verifyClerkSessionToken`: with
+  an `org_id` claim, pass a `person` credential carrying `verifiedOrgId` and
+  `verifiedOrgRole`; without one, pass `person-no-org`. A person credential
+  that merely lacks `verifiedOrgId` is garbled and is `anonymous`, never `pre-org`.
+- Branch on `standing`, never on the absence of a field. `pre-org` is not
+  `anonymous`: refuse it where an organisation is needed, but answer it as a
+  signed-in caller (see the refusal rules of your read doors).
+
+## Protecting an MCP server as an OAuth resource (`/resource-server`)
+
+An MCP server that requires a bearer token is an OAuth 2.1 protected resource.
+These primitives are the whole resource side; they fetch nothing and call no
+network.
+
+```ts
+import {
+  buildProtectedResourceMetadata,
+  unauthorizedChallenge,
+  deriveClerkDiscoveryUrls,
+  verifyMcpAccessToken,
+} from "@vantageos/cloud-identity/resource-server";
+
+// GET /.well-known/oauth-protected-resource  (RFC 9728)
+const metadata = buildProtectedResourceMetadata({
+  resource: "https://mcp.example.com/mcp",
+  authorizationServers: ["https://clerk.example.com"],
+  scopesSupported: ["mcp:read", "mcp:write"],
+});
+
+// On every MCP request
+const r = await verifyMcpAccessToken(req.headers.authorization, {
+  realm: "mcp",
+  resourceMetadataUrl: "https://mcp.example.com/.well-known/oauth-protected-resource",
+  issuer: "https://clerk.example.com",
+  audience: "https://mcp.example.com/mcp", // this resource: required
+  jwks: () => fetchJwks(deriveClerkDiscoveryUrls("https://clerk.example.com").jwksUrl),
+});
+if (!r.ok) return respond(r.status, "headers" in r ? r.headers : {});
+// r.session.userId, r.session.claims
+```
+
+- `buildProtectedResourceMetadata` returns the RFC 9728 document
+  (`ProtectedResourceMetadataConfig` in, `ProtectedResourceMetadata` out).
+- `unauthorizedChallenge` returns `{ status: 401, headers }` whose
+  `WWW-Authenticate` always carries `resource_metadata`, plus `error`,
+  `error_description` and `scope` when given (`UnauthorizedChallengeConfig`,
+  `UnauthorizedChallenge`). Values are escaped; a line break throws.
+- `deriveClerkDiscoveryUrls` returns `ClerkDiscoveryUrls`
+  (`discoveryUrl`, `jwksUrl`) for an `https` issuer.
+- `verifyMcpAccessToken` reuses `verifyClerkSessionToken` (RS256 only) and
+  requires the token's `aud` to contain `audience`. It returns the verified
+  session, or a `CREDENTIAL_REFUSED` refusal with the `401` envelope
+  (`McpResourceServerConfig`, `VerifyMcpAccessTokenResult`):
+  `bearer-missing` and `bearer-malformed` answer `invalid_request`,
+  `token-invalid` answers `invalid_token` (wrong signature, issuer, audience,
+  expiry or not-before are one answer), and an unreachable key set is `503`
+  with no challenge (`jwks-unavailable`). A missing issuer or audience throws.
+- Limits, stated: the token needs a `sub` and a `kid` (the Clerk session shape);
+  the consumer fetches and caches the key set; no scope check is made on the
+  token (read `r.session.claims`).
+
+## An organisation is its permanent ID (0.16.0)
+
+A label (the slug an org can be renamed to) is display text. These functions
+decide "which organisation" from the permanent org ID, with the store supplied
+as adapters, and refuse by default. All are in `./org-by-id` and the root.
+
+**`resolveOrgFromClaim(claims, lookups, opts)`** takes the claim record of a
+VERIFIED credential (never a request field) and returns
+`{ ok: true, org: { id, label, allowedOrchestrators, scopes, orgKind } }`
+or a typed `RBAC_DENIED` refusal. The `org_id` claim (also read from
+`organizationId` and `orgId`, only when shaped like a Clerk org ID) selects the
+mapping row through `lookups.orgById`; a stale label in the token is ignored,
+so a rename never changes who the caller is. Refused: no claim, an ID no
+mapping holds, an inactive org, a row that does not repeat the ID asked for, a
+malformed row, a missing or throwing adapter.
+
+```ts
+const r = await resolveOrgFromClaim(identity, {
+  orgById: (id) => db.mappingByClerkOrgId(id),
+}, { door: "tasks:list" });
+if (!r.ok) throw new IdentityRefusalError(r.refusal);
+```
+
+**`sameOrg(a, b, opts)`**, **`isFleetStamp(stamp, operator, opts)`** and
+**`sameTenantStamp(a, b, operator, opts)`** compare `OrgRef` values
+(`{ id?, label? }`). Two IDs are equal or they are not; unstamped is never
+a match; `isFleetStamp` is true for an unstamped stamp or the operator's, and
+`sameTenantStamp` is true for the same org or when both are the fleet's.
+
+**`findOperatorOrg(lookups, opts)`** finds the operator organisation from
+`lookups.activeOrganisations(limit)`: `one`, `none`, `many`, `overCap`
+(`cap` defaults to 1000, the read is `cap + 1`) or `unreadable`. Only `one` is
+an operator; pass `undefined` as `operator` otherwise and only unstamped rows
+are the fleet's.
+
+**`resolveOrgIdForLabelBackfillOnly(label, lookups)`** derives the permanent
+ID of the org a label names, for a ONE-OFF BACKFILL that stamps rows written
+before IDs existed. It must never be called on a request path: a request
+decides its organisation from the verified `org_id` claim
+(`resolveOrgFromClaim`), and a miss there is a refusal, never a retry by label.
+It returns `{ present: true, orgId }` or a typed `ORG_ID_ABSENT` absence
+(`no-label`, `lookup-failed`, `not-mapped`, `record-invalid`, `id-not-filled`).
+It never invents an ID.
+
+**`orgMappingRowSchema`** is the Zod shape of a mapping row an adapter returns
+(`id`, `label`, `active`, `allowedOrchestrators`, `scopes`, `orgKind`).
+
+Types: `OrgRef`, `OrgMappingRow`, `OrgMappingLookups`,
+`ResolvedOrg`, `ResolveOrgFromClaimOptions`, `ResolveOrgFromClaimResult`,
+`OrgIdAbsence`, `OrgIdAbsenceReason`, `OrgIdResolution`, `OperatorOrgLookups`,
+`FindOperatorOrgOptions`, `OperatorOrgResult`.
+
+**No label resolution.** No function above compares or selects by label, and
+no option turns that on: a reference or credential without an org ID names no
+organisation and is refused. A store that has not filled every ID is filled
+once, with `resolveOrgIdForLabelBackfillOnly`, before the consumer relies on
+these functions.
+
 ## What this package does not do
 
 Worth reading before you rely on it.

package/dist/identity-refusal.d.ts

@@ -13,7 +13,7 @@
  * closed vocabulary for the person path.
  */
 export type IdentityRefusalCode = "RBAC_DENIED" | "CREDENTIAL_REFUSED";
-export type IdentityRefusalReason = "unknown-role" | "unknown-minimum-role" | "invalid-role-order" | "role-below-minimum" | "role-claim-absent" | "role-claim-unmapped" | "invalid-role-mapping" | "membership-invalid-input" | "membership-lookup-failed" | "membership-not-found" | "membership-record-invalid" | "membership-inactive" | "other-organisation" | "no-verified-organisation" | "role-not-admin" | "namespace-invalid" | "no-write-prefixes" | "namespace-write-denied" | "secret-not-configured" | "secret-mismatch" | "credential-invalid" | "principal-lookup-failed" | "principal-not-found" | "principal-record-invalid" | "principal-inactive" | "organisation-not-active" | "reserved-fleet-scope" | "acting-agent-other-organisation" | "target-unstamped" | "target-other-organisation" | "target-owner-mismatch" | "principal-not-a-person" | "list-absent" | "list-empty" | "principal-not-an-agent" | "principal-not-listed";
+export type IdentityRefusalReason = "unknown-role" | "unknown-minimum-role" | "invalid-role-order" | "role-below-minimum" | "role-claim-absent" | "role-claim-unmapped" | "invalid-role-mapping" | "membership-invalid-input" | "membership-lookup-failed" | "membership-not-found" | "membership-record-invalid" | "membership-inactive" | "other-organisation" | "no-verified-organisation" | "role-not-admin" | "namespace-invalid" | "no-write-prefixes" | "namespace-write-denied" | "secret-not-configured" | "secret-mismatch" | "credential-invalid" | "principal-lookup-failed" | "principal-not-found" | "principal-record-invalid" | "principal-inactive" | "organisation-not-active" | "reserved-fleet-scope" | "acting-agent-other-organisation" | "target-unstamped" | "target-other-organisation" | "target-owner-mismatch" | "principal-not-a-person" | "list-absent" | "list-empty" | "principal-not-an-agent" | "principal-not-listed" | "bearer-missing" | "bearer-malformed" | "token-invalid" | "jwks-unavailable" | "org-mapping-lookup-failed" | "org-mapping-not-found" | "org-mapping-record-invalid";
 export type IdentityRefusal = {
     code: IdentityRefusalCode;
     reason: IdentityRefusalReason;

package/dist/identity-refusal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-refusal.d.ts","sourceRoot":"","sources":["../src/identity-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,oBAAoB,CAAC;AAEvE,MAAM,MAAM,qBAAqB,GAE7B,cAAc,GACd,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GAEtB,0BAA0B,GAC1B,0BAA0B,GAC1B,sBAAsB,GACtB,2BAA2B,GAC3B,qBAAqB,GACrB,oBAAoB,GAEpB,0BAA0B,GAC1B,gBAAgB,GAEhB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,GAExB,uBAAuB,GACvB,iBAAiB,GAEjB,oBAAoB,GACpB,yBAAyB,GACzB,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,yBAAyB,GACzB,sBAAsB,GACtB,iCAAiC,GACjC,kBAAkB,GAClB,2BAA2B,GAC3B,uBAAuB,GAEvB,wBAAwB,GAExB,aAAa,GACb,YAAY,GACZ,wBAAwB,GACxB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,0EAA0E;AAC1E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBACtB,OAAO,EAAE,eAAe;CAKrC;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CACrB,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,eAAe,CAEjB"}
+{"version":3,"file":"identity-refusal.d.ts","sourceRoot":"","sources":["../src/identity-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG,oBAAoB,CAAC;AAEvE,MAAM,MAAM,qBAAqB,GAE7B,cAAc,GACd,sBAAsB,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GAEtB,0BAA0B,GAC1B,0BAA0B,GAC1B,sBAAsB,GACtB,2BAA2B,GAC3B,qBAAqB,GACrB,oBAAoB,GAEpB,0BAA0B,GAC1B,gBAAgB,GAEhB,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,GAExB,uBAAuB,GACvB,iBAAiB,GAEjB,oBAAoB,GACpB,yBAAyB,GACzB,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,yBAAyB,GACzB,sBAAsB,GACtB,iCAAiC,GACjC,kBAAkB,GAClB,2BAA2B,GAC3B,uBAAuB,GAEvB,wBAAwB,GAExB,aAAa,GACb,YAAY,GACZ,wBAAwB,GACxB,sBAAsB,GAEtB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,kBAAkB,GAElB,2BAA2B,GAC3B,uBAAuB,GACvB,4BAA4B,CAAC;AAEjC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,0EAA0E;AAC1E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBACtB,OAAO,EAAE,eAAe;CAKrC;AAED,gEAAgE;AAChE,wBAAgB,OAAO,CACrB,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,eAAe,CAEjB"}

package/dist/identity-refusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"identity-refusal.js","sourceRoot":"","sources":["../src/identity-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2DH,0EAA0E;AAC1E,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,OAAO,CAAkB;IAClC,YAAY,OAAwB;QAClC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CACrB,IAAyB,EACzB,MAA6B,EAC7B,IAAY,EACZ,MAAc;IAEd,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}
+{"version":3,"file":"identity-refusal.js","sourceRoot":"","sources":["../src/identity-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoEH,0EAA0E;AAC1E,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,OAAO,CAAkB;IAClC,YAAY,OAAwB;QAClC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CACrB,IAAyB,EACzB,MAA6B,EAC7B,IAAY,EACZ,MAAc;IAEd,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -37,6 +37,10 @@ export { isRowInTenant, resolveMembership, requireOrgAdmin, membershipRecordSche
 export type { MembershipRecord, ResolvedMembership, ResolveMembershipInput, ResolveMembershipResult, RequireOrgAdminInput, } from "./tenant-membership.js";
 export { assertNamespaceWrite } from "./namespace-write.js";
 export { timingSafeEqualSync, assertSecretSync } from "./secret-compare-sync.js";
-export { actingCredentialSchema, principalRowSchema, organisationRowSchema, resolveActingPrincipal, assertTargetBelongsTo, assertOrgAdmin, assertPrincipalListed, } from "./principal-by-id.js";
-export type { ActingCredential, PrincipalRow, OrganisationRow, PrincipalLookups, OrgKind, OrgKindLookups, ActingPrincipalKind, ActingPrincipal, ResolveActingPrincipalResult, TargetIds, AssertTargetOptions, AssertTargetResult, AssertOrgAdminOptions, AssertOrgAdminResult, PrincipalIdList, AssertPrincipalListedOptions, AssertPrincipalListedResult, } from "./principal-by-id.js";
+export { actingCredentialSchema, principalRowSchema, organisationRowSchema, resolveActingPrincipal, assertTargetBelongsTo, filterTargetsBelongingTo, assertOrgAdmin, assertPrincipalListed, assertRecipientAddressable, resolveCallerStanding, } from "./principal-by-id.js";
+export type { ActingCredential, PrincipalRow, OrganisationRow, PrincipalLookups, OrgKind, OrgKindLookups, ActingPrincipalKind, ActingPrincipal, ResolveActingPrincipalResult, TargetIds, AssertTargetOptions, AssertTargetResult, FilterTargetsResult, AssertOrgAdminOptions, AssertOrgAdminResult, PrincipalIdList, AssertPrincipalListedOptions, AssertPrincipalListedResult, RecipientIds, RecipientLookups, AssertRecipientAddressableOptions, AssertRecipientAddressableResult, CallerCredential, AssertCallerStandingOptions, CallerStanding, } from "./principal-by-id.js";
+export { buildProtectedResourceMetadata, unauthorizedChallenge, deriveClerkDiscoveryUrls, verifyMcpAccessToken, } from "./resource-server.js";
+export type { ProtectedResourceMetadataConfig, ProtectedResourceMetadata, UnauthorizedChallengeConfig, UnauthorizedChallenge, ClerkDiscoveryUrls, McpResourceServerConfig, VerifyMcpAccessTokenResult, } from "./resource-server.js";
+export { sameOrg, isFleetStamp, sameTenantStamp, resolveOrgFromClaim, resolveOrgIdForLabelBackfillOnly, findOperatorOrg, orgMappingRowSchema, } from "./org-by-id.js";
+export type { OrgRef, OrgMappingRow, OrgMappingLookups, ResolvedOrg, ResolveOrgFromClaimOptions, ResolveOrgFromClaimResult, OrgIdAbsence, OrgIdAbsenceReason, OrgIdResolution, OperatorOrgLookups, FindOperatorOrgOptions, OperatorOrgResult, } from "./org-by-id.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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -38,5 +38,16 @@ export { timingSafeEqualSync, assertSecretSync } from "./secret-compare-sync.js"
 // 0.11.0 — The acting principal by ID and the target checked by ID. A name is
 // a display label: it never selects a row and never authorises one.
 // 0.12.0 — assertOrgAdmin: the org-admin proof on a principal resolved by ID.
-export { actingCredentialSchema, principalRowSchema, organisationRowSchema, resolveActingPrincipal, assertTargetBelongsTo, assertOrgAdmin, assertPrincipalListed, } from "./principal-by-id.js";
+export { actingCredentialSchema, principalRowSchema, organisationRowSchema, resolveActingPrincipal, assertTargetBelongsTo, filterTargetsBelongingTo, assertOrgAdmin, assertPrincipalListed, assertRecipientAddressable, resolveCallerStanding, } from "./principal-by-id.js";
+// 0.15.0 — Resource-server primitives: RFC 9728 protected resource metadata,
+// the RFC 6750 401 challenge, issuer discovery URLs and MCP access-token
+// verification bound to this resource. Replaces the standalone resource-server
+// package; one identity layer.
+export { buildProtectedResourceMetadata, unauthorizedChallenge, deriveClerkDiscoveryUrls, verifyMcpAccessToken, } from "./resource-server.js";
+// 0.16.0 — An organisation is its permanent ID: the credential's org_id claim to
+// the org's mapping row, the ID comparisons and the operator org. Labels
+// (slugs) never select or prove an org; no option turns that on. The
+// label-to-ID derivation is exported only as
+// `resolveOrgIdForLabelBackfillOnly`, for a one-off backfill.
+export { sameOrg, isFleetStamp, sameTenantStamp, resolveOrgFromClaim, resolveOrgIdForLabelBackfillOnly, findOperatorOrg, orgMappingRowSchema, } from "./org-by-id.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,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,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;AAY/B,+EAA+E;AAC/E,mEAAmE;AACnE,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAa7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAOhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQ7D,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AASlE,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAMjF,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAc/B,+EAA+E;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAM7D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAO/E,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAQhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjF,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAC9E,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,cAAc,EACd,qBAAqB,GACtB,MAAM,sBAAsB,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,sBAAsB,EACtB,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;AAY/B,+EAA+E;AAC/E,mEAAmE;AACnE,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAa7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAOhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQ7D,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AASlE,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAMjF,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAc/B,+EAA+E;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAM7D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAO/E,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAQhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjF,8EAA8E;AAC9E,oEAAoE;AACpE,8EAA8E;AAC9E,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AA6B9B,6EAA6E;AAC7E,yEAAyE;AACzE,+EAA+E;AAC/E,+BAA+B;AAC/B,OAAO,EACL,8BAA8B,EAC9B,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAW9B,iFAAiF;AACjF,yEAAyE;AACzE,qEAAqE;AACrE,6CAA6C;AAC7C,8DAA8D;AAC9D,OAAO,EACL,OAAO,EACP,YAAY,EACZ,eAAe,EACf,mBAAmB,EACnB,gCAAgC,EAChC,eAAe,EACf,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/org-by-id.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @vantageos/cloud-identity — an organisation is its permanent ID.
+ *
+ * Everything here decides "which organisation" from the permanent org ID a
+ * verified credential or a stored row carries. A label (the slug an org can be
+ * renamed to) is display text: it never selects an org and never proves two
+ * references are one org.
+ *
+ * Refusal, always. There is no option that compares or resolves by label: a
+ * reference or credential without an org ID names no organisation, and a
+ * mapping is reached only by an ID.
+ *
+ * The store is the consumer's: every read is an adapter it supplies, called
+ * with the key as presented, byte for byte. A missing, throwing or malformed
+ * adapter refuses. An adapter's error text is never surfaced.
+ */
+import { z } from "zod";
+import { type IdentityRefusal } from "./identity-refusal.js";
+import type { OrgKind } from "./principal-by-id.js";
+/**
+ * An organisation as a row or a caller names it: the permanent ID and the
+ * label. Either may be absent. Both absent is "unstamped", which names no
+ * organisation.
+ */
+export type OrgRef = {
+    /** The permanent org ID. */
+    id?: string | null;
+    /** The renamable label (slug). Display text; never compared. */
+    label?: string | null;
+};
+/**
+ * Do two references name the same organisation? Only by ID, when both carry
+ * one. A label never matches, and absence is not a match: two unstamped
+ * references are NOT the same organisation here.
+ */
+export declare function sameOrg(a: OrgRef | null | undefined, b: OrgRef | null | undefined): boolean;
+/**
+ * Is a stamp the fleet's: unstamped, or the operator organisation's? The
+ * operator is read from stored data by the caller (see `findOperatorOrg`);
+ * pass `undefined` when there is not exactly one, and only an unstamped stamp
+ * is the fleet's. An empty-string stamp is neither unstamped nor the operator.
+ */
+export declare function isFleetStamp(stamp: OrgRef | null | undefined, operator: OrgRef | null | undefined): boolean;
+/**
+ * Do two stamps name the same tenant: the same organisation, or both the
+ * fleet's? Two IDs that differ are two tenants even under one label.
+ */
+export declare function sameTenantStamp(a: OrgRef | null | undefined, b: OrgRef | null | undefined, operator: OrgRef | null | undefined): boolean;
+/**
+ * The consumer's organisation mapping row, as an adapter returns it. `id` is
+ * the permanent org ID and may be absent while the store is being filled;
+ * `label` is the slug. Extra fields are allowed and ignored.
+ */
+export declare const orgMappingRowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodString;
+    active: z.ZodBoolean;
+    allowedOrchestrators: z.ZodArray<z.ZodString>;
+    scopes: z.ZodArray<z.ZodString>;
+    orgKind: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type OrgMappingRow = z.input<typeof orgMappingRowSchema>;
+type Lookup<A extends unknown[], R> = (...args: A) => Promise<R | null | undefined> | R | null | undefined;
+/** Indexed reads of the mapping store. Only the lookups of the path taken are called. */
+export type OrgMappingLookups = {
+    /** The mapping row whose permanent ID is exactly the one asked for. */
+    orgById?: Lookup<[orgId: string], OrgMappingRow>;
+    /** The mapping row whose label is exactly the one asked for. Read only by `resolveOrgIdForLabelBackfillOnly`. */
+    orgByLabel?: Lookup<[label: string], OrgMappingRow>;
+};
+/** The org a credential resolves to, with the roster and scopes of its mapping row. */
+export type ResolvedOrg = {
+    /** The permanent org ID: the one the credential carried and the mapping holds. */
+    id: string;
+    /** The org's CURRENT label. Display text. */
+    label: string;
+    allowedOrchestrators: string[];
+    scopes: string[];
+    orgKind: OrgKind | null;
+};
+export type ResolveOrgFromClaimOptions = {
+    /** The consumer's name for the door; carried on every refusal. */
+    door?: string;
+};
+export type ResolveOrgFromClaimResult = {
+    ok: true;
+    org: ResolvedOrg;
+} | {
+    ok: false;
+    refusal: IdentityRefusal;
+};
+/**
+ * Resolves a VERIFIED credential's claims to the stored mapping row of its
+ * organisation, or refuses. The claim's org ID selects the row; nothing the
+ * request supplies does.
+ *
+ * A credential carrying no usable org ID is refused
+ * (`no-verified-organisation`) and an ID no mapping holds is refused
+ * (`org-mapping-not-found`). A label claim (a slug) is never read: it neither
+ * selects a mapping nor rescues a missing ID.
+ *
+ * `claims` is the verified identity's own claim record, never a request field.
+ */
+export declare function resolveOrgFromClaim(claims: Record<string, unknown> | null | undefined, lookups: OrgMappingLookups | null | undefined, options?: ResolveOrgFromClaimOptions): Promise<ResolveOrgFromClaimResult>;
+export type OrgIdAbsenceReason = "no-label" | "lookup-failed" | "not-mapped" | "record-invalid" | "id-not-filled";
+/** The typed absence of an ID. A non-empty object: never mistaken for an ID or for nothing. */
+export type OrgIdAbsence = {
+    code: "ORG_ID_ABSENT";
+    reason: OrgIdAbsenceReason;
+};
+export type OrgIdResolution = {
+    present: true;
+    orgId: string;
+} | {
+    present: false;
+    absence: OrgIdAbsence;
+};
+/**
+ * BACKFILL ONLY. Derives the permanent org ID of the organisation a label
+ * names, from the consumer's stored mapping, so a one-off migration can stamp
+ * rows written before IDs existed.
+ *
+ * MUST NEVER be called on a request path. A request decides its organisation
+ * from the verified credential's `org_id` claim (`resolveOrgFromClaim`); a miss
+ * there is a refusal, never a retry by label. A label is renamable display
+ * text: resolving an org from it on a request is the name-to-ID defect this
+ * module exists to close, and the export name carries that restriction so a
+ * reviewer sees it at every call site.
+ *
+ * A derivation and not an authorization: it answers for an inactive mapping
+ * too. It never invents an ID: a mapping with none filled is `id-not-filled`.
+ */
+export declare function resolveOrgIdForLabelBackfillOnly(label: string | null | undefined, lookups: OrgMappingLookups | null | undefined): Promise<OrgIdResolution>;
+export type OperatorOrgLookups = {
+    /**
+     * The ACTIVE organisation mapping rows, at most `limit` of them. Called with
+     * `cap + 1` so a filled read is recognisable as over the cap.
+     */
+    activeOrganisations?: (limit: number) => unknown;
+};
+export type FindOperatorOrgOptions = {
+    /** Read bound. Default 1000. A read over the cap is never decided from. */
+    cap?: number;
+};
+export type OperatorOrgResult = {
+    kind: "one";
+    org: {
+        id: string | undefined;
+        label: string;
+    };
+} | {
+    kind: "none";
+} | {
+    kind: "many";
+    count: number;
+} | {
+    kind: "overCap";
+} | {
+    kind: "unreadable";
+};
+/**
+ * Finds the operator organisation (the fleet) from stored mapping rows: the
+ * single ACTIVE row whose kind is exactly `"operator"`. None, several, an
+ * over-cap read, an unreadable store and a malformed row are each a typed
+ * non-answer, so the caller can only treat the fleet as "no single operator"
+ * (fail closed) and never widen from a guess.
+ */
+export declare function findOperatorOrg(lookups: OperatorOrgLookups | null | undefined, options?: FindOperatorOrgOptions): Promise<OperatorOrgResult>;
+export {};
+//# sourceMappingURL=org-by-id.d.ts.map

package/dist/org-by-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"org-by-id.d.ts","sourceRoot":"","sources":["../src/org-by-id.ts"],"names":[],"mappings":"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"}