@vantageos/cloud-identity 0.13.0 → 0.16.0

package/dist/org-by-id.js

@@ -0,0 +1,232 @@
+/**
+ * @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 { refusal } from "./identity-refusal.js";
+import { resolveTenantIdOrAbsent } from "./org-guard.js";
+function nonEmpty(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isUnstamped(ref) {
+    return (ref === null ||
+        ref === undefined ||
+        ((ref.id === null || ref.id === undefined) &&
+            (ref.label === null || ref.label === undefined)));
+}
+// ---------------------------------------------------------------------------
+// sameOrg / isFleetStamp / sameTenantStamp
+// ---------------------------------------------------------------------------
+/**
+ * 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 function sameOrg(a, b) {
+    if (!a || !b)
+        return false;
+    return nonEmpty(a.id) && nonEmpty(b.id) && a.id === b.id;
+}
+/**
+ * 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 function isFleetStamp(stamp, operator) {
+    if (isUnstamped(stamp))
+        return true;
+    return operator !== null && operator !== undefined && sameOrg(stamp, operator);
+}
+/**
+ * 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 function sameTenantStamp(a, b, operator) {
+    if (isFleetStamp(a, operator) && isFleetStamp(b, operator))
+        return true;
+    return sameOrg(a, b);
+}
+// ---------------------------------------------------------------------------
+// The stored mapping row
+// ---------------------------------------------------------------------------
+/**
+ * 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 const orgMappingRowSchema = z.object({
+    id: z.string().min(1).nullish(),
+    label: z.string().min(1),
+    active: z.boolean(),
+    allowedOrchestrators: z.array(z.string()),
+    scopes: z.array(z.string()),
+    orgKind: z.string().nullish(),
+});
+function kindOf(raw) {
+    return raw === "operator" || raw === "client" ? raw : null;
+}
+/** Calls an adapter; a missing or throwing one is `called: false`. */
+async function call(lookup, ...args) {
+    if (typeof lookup !== "function")
+        return { called: false };
+    try {
+        const raw = await lookup(...args);
+        return { called: true, row: raw ?? null };
+    }
+    catch {
+        return { called: false };
+    }
+}
+const CLERK_ORG_ID_SHAPE = /^org_[A-Za-z0-9]+$/;
+const ID_CLAIMS = ["org_id", "organizationId", "orgId"];
+/** The first claim that is shaped like a Clerk org ID and resolves as a tenant. */
+function claimedOrgId(claims) {
+    for (const name of ID_CLAIMS) {
+        const value = claims[name];
+        if (typeof value !== "string" || !CLERK_ORG_ID_SHAPE.test(value))
+            continue;
+        const resolved = resolveTenantIdOrAbsent({ kind: "session", identity: { orgId: value } });
+        if (resolved.present)
+            return resolved.tenantId;
+    }
+    return undefined;
+}
+/**
+ * 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 async function resolveOrgFromClaim(claims, lookups, options) {
+    const door = options?.door ?? "resolveOrgFromClaim";
+    const deny = (reason, detail) => ({
+        ok: false,
+        refusal: refusal("RBAC_DENIED", reason, door, detail),
+    });
+    const record = claims && typeof claims === "object" ? claims : {};
+    const orgId = claimedOrgId(record);
+    if (orgId === undefined) {
+        return deny("no-verified-organisation", "The credential carries no verified organisation.");
+    }
+    const served = (row, id) => {
+        if (row.active !== true) {
+            return deny("organisation-not-active", "The organisation is not mapped or not active.");
+        }
+        return {
+            ok: true,
+            org: {
+                id,
+                label: row.label,
+                allowedOrchestrators: row.allowedOrchestrators,
+                scopes: row.scopes,
+                orgKind: kindOf(row.orgKind),
+            },
+        };
+    };
+    const invalid = deny("org-mapping-record-invalid", "The organisation mapping record is not well formed.");
+    const unreadable = deny("org-mapping-lookup-failed", "The organisation mapping could not be read, so none is resolved.");
+    const found = await call(lookups?.orgById, orgId);
+    if (!found.called)
+        return unreadable;
+    if (found.row === null) {
+        return deny("org-mapping-not-found", "No organisation mapping holds the credential's organisation ID.");
+    }
+    const parsed = orgMappingRowSchema.safeParse(found.row);
+    if (!parsed.success || parsed.data.id !== orgId)
+        return invalid;
+    return served(parsed.data, orgId);
+}
+/**
+ * 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 async function resolveOrgIdForLabelBackfillOnly(label, lookups) {
+    const absent = (reason) => ({
+        present: false,
+        absence: { code: "ORG_ID_ABSENT", reason },
+    });
+    if (!nonEmpty(label))
+        return absent("no-label");
+    const found = await call(lookups?.orgByLabel, label);
+    if (!found.called)
+        return absent("lookup-failed");
+    if (found.row === null)
+        return absent("not-mapped");
+    const parsed = orgMappingRowSchema.safeParse(found.row);
+    if (!parsed.success || parsed.data.label !== label)
+        return absent("record-invalid");
+    if (parsed.data.id === undefined || parsed.data.id === null)
+        return absent("id-not-filled");
+    return { present: true, orgId: parsed.data.id };
+}
+const DEFAULT_OPERATOR_READ_CAP = 1000;
+/**
+ * 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 async function findOperatorOrg(lookups, options) {
+    const cap = options?.cap ?? DEFAULT_OPERATOR_READ_CAP;
+    const read = lookups?.activeOrganisations;
+    if (typeof read !== "function")
+        return { kind: "unreadable" };
+    let raw;
+    try {
+        raw = await read(cap + 1);
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+    if (!Array.isArray(raw))
+        return { kind: "unreadable" };
+    if (raw.length > cap)
+        return { kind: "overCap" };
+    const operators = [];
+    for (const item of raw) {
+        const parsed = orgMappingRowSchema.safeParse(item);
+        if (!parsed.success)
+            return { kind: "unreadable" };
+        if (parsed.data.active === true && parsed.data.orgKind === "operator") {
+            operators.push(parsed.data);
+        }
+    }
+    if (operators.length === 0)
+        return { kind: "none" };
+    if (operators.length > 1)
+        return { kind: "many", count: operators.length };
+    const [only] = operators;
+    return { kind: "one", org: { id: only.id ?? undefined, label: only.label } };
+}
+//# sourceMappingURL=org-by-id.js.map

package/dist/org-by-id.js.map

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

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

@@ -211,6 +211,40 @@ export declare function resolveActingPrincipal(credential: ActingCredential | nu
  *     absent owner is refused.
  */
 export declare function assertTargetBelongsTo(principal: ActingPrincipal | null | undefined, target: TargetIds | null | undefined, lookups: OrgKindLookups, opts?: AssertTargetOptions): Promise<AssertTargetResult>;
+export type FilterTargetsResult<T> = {
+    ok: true;
+    rows: T[];
+} | {
+    ok: false;
+    refusal: IdentityRefusal;
+};
+/**
+ * Keeps the rows that belong to the principal, deciding by STORED ID only.
+ * The ID-keyed replacement for the name-keyed `scopeFilterList`.
+ *
+ * Each row is judged by `assertTargetBelongsTo` (never re-derived here), so
+ * the same organisation, operator-org, unstamped, `ownerOnly` and
+ * `fleetCrossOrg` rules apply.
+ *
+ *   - The principal is proved FIRST, before any row is read. An absent or
+ *     unresolved principal, or a failed organisation-kind lookup for it,
+ *     returns `{ ok: false, refusal }` naming the door, even for an empty
+ *     list: a refusal is never an `ok: true` with no rows.
+ *   - `fleetCrossOrg: true` from a principal that is not `kind: "fleet"` is a
+ *     misconfigured door and is refused `reserved-fleet-scope` up front, for
+ *     any list. Per row, `reserved-fleet-scope` therefore only means "this row
+ *     is in the operator scope" and the row is dropped.
+ *   - A resolved principal whose rows all belong elsewhere gets
+ *     `{ ok: true, rows: [] }`: an absence, distinguishable from a refusal.
+ *   - A row that does not belong (other organisation, operator-org row,
+ *     unstamped, owner mismatch) is dropped. A same-NAME row of another
+ *     organisation is dropped: no name field is read.
+ *   - A lookup failure on any row refuses the whole call. It is never a
+ *     silent drop and never a pass; any refusal reason not known to mean
+ *     "this row is not yours" refuses too.
+ *   - The order of the kept rows is the order of the input.
+ */
+export declare function filterTargetsBelongingTo<T extends TargetIds>(principal: ActingPrincipal | null | undefined, rows: readonly T[], lookups: OrgKindLookups, opts?: AssertTargetOptions): Promise<FilterTargetsResult<T>>;
 export type AssertOrgAdminOptions = {
     /**
      * The role values that count as organisation admin, exactly as the verified
@@ -290,5 +324,109 @@ export type AssertPrincipalListedResult = {
  * The fleet sentinel is out of scope here.
  */
 export declare function assertPrincipalListed(principal: ActingPrincipal | null | undefined, list: PrincipalIdList | null | undefined, opts?: AssertPrincipalListedOptions): AssertPrincipalListedResult;
+/** The recipient of a message, named by its stored agent ID and organisation ID. */
+export type RecipientIds = {
+    /** The recipient agent's stored ID. */
+    agentId: string;
+    /** The recipient agent's stored organisation ID. */
+    orgId: string;
+};
+/**
+ * The lookups `assertRecipientAddressable` reads: the organisation kind, and
+ * the stored roster of agent IDs of one organisation (a client's list of the
+ * fleet agents it may reach). `null`, a miss or a throw is an unresolvable
+ * roster and refuses.
+ */
+export type RecipientLookups = OrgKindLookups & {
+    rosterOf?: Lookup<[orgId: string], PrincipalIdList>;
+};
+export type AssertRecipientAddressableOptions = {
+    /** The consumer's name for the door; carried on every refusal. */
+    door?: string;
+};
+export type AssertRecipientAddressableResult = {
+    ok: true;
+} | {
+    ok: false;
+    refusal: IdentityRefusal;
+};
+/**
+ * Decides whether a sender may address a recipient, across organisations
+ * included, by AGENT ID only. The sender must come from
+ * `resolveActingPrincipal`. No name is read anywhere; a name never matches.
+ *
+ * Admitted iff one of these holds:
+ *   (a) same organisation: the sender's `orgId` equals the recipient's;
+ *   (b) client to operator: the sender is in a client organisation, the
+ *       recipient is in the operator organisation, and the RECIPIENT's ID is
+ *       on the SENDER organisation's roster;
+ *   (c) operator to client: the sender is in the operator organisation, the
+ *       recipient is in a client organisation, and the SENDER's ID is on the
+ *       RECIPIENT organisation's roster.
+ *
+ * Everything else is refused with a typed `RBAC_DENIED` carrying the door
+ * (default `"assertRecipientAddressable"`): an absent sender or one without an
+ * ID (`credential-invalid`), a sender that is not `kind: "agent"`
+ * (`principal-not-an-agent`), an absent recipient or one without an agent ID
+ * or organisation (`target-unstamped`), client to client across organisations
+ * and an organisation kind that is neither operator nor client
+ * (`target-other-organisation`), a missing or throwing `orgKindOf` /
+ * `rosterOf` (`principal-lookup-failed`), an absent roster (`list-absent`), and
+ * a roster that is empty, stored under the wrong organisation or does not list
+ * the ID (the refusals of {@link assertPrincipalListed}, which is reused for
+ * that check).
+ */
+export declare function assertRecipientAddressable(sender: ActingPrincipal | null | undefined, recipient: RecipientIds | null | undefined, lookups: RecipientLookups, opts?: AssertRecipientAddressableOptions): Promise<AssertRecipientAddressableResult>;
+/**
+ * A verified session that carries a person but NO organisation (a signed-in
+ * user who has not joined one). `resolveActingPrincipal` cannot express this:
+ * a person credential requires `verifiedOrgId`, so a no-organisation session
+ * is refused there exactly as a garbled credential is. This kind exists so
+ * the consumer can say "verified, and no organisation" on purpose; an absent
+ * `verifiedOrgId` on a `person` credential stays a garbled credential.
+ */
+declare const preOrgCredentialSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"person-no-org">;
+    personId: z.ZodString;
+}, z.core.$strict>;
+export type CallerCredential = ActingCredential | z.input<typeof preOrgCredentialSchema>;
+export type AssertCallerStandingOptions = {
+    /** Role values that make a person an organisation admin; see `assertOrgAdmin`. */
+    adminRoles: readonly string[];
+    /** The consumer's name for the door; carried on every refusal. */
+    door?: string;
+};
+/**
+ * The four callers, said apart. `anonymous` means no caller could be
+ * resolved (no credential, a garbled one, a miss, an inactive row) and carries
+ * the typed refusal; it is never what a signed-in session without an
+ * organisation becomes.
+ */
+export type CallerStanding = {
+    standing: "anonymous";
+    refusal: IdentityRefusal;
+} | {
+    standing: "pre-org";
+    personId: string;
+} | {
+    standing: "member";
+    principal: ActingPrincipal;
+} | {
+    standing: "admin";
+    principal: ActingPrincipal;
+} | {
+    standing: "fleet";
+    principal: ActingPrincipal;
+};
+/**
+ * Derives a caller's STANDING from a verified credential. It adds one case to
+ * the existing primitives, the signed-in session with no organisation, and
+ * reuses them for everything else: `resolveActingPrincipal` decides who the
+ * caller is (and `fleet`), `assertOrgAdmin` decides `admin` against the
+ * principal's own organisation. Any other resolved principal (a person
+ * without the admin role, an agent, a non-operator service account) is a
+ * `member`; read `principal.kind` to tell them apart.
+ */
+export declare function resolveCallerStanding(credential: CallerCredential | null | undefined, lookups: PrincipalLookups, opts: AssertCallerStandingOptions): Promise<CallerStanding>;
 export {};
 //# sourceMappingURL=principal-by-id.d.ts.map

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

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

package/dist/principal-by-id.js

@@ -343,6 +343,64 @@ export async function assertTargetBelongsTo(principal, target, lookups, opts = {
     }
     return { ok: true };
 }
+/** Refusal reasons that say only "this ROW is not the principal's". */
+const ROW_NOT_OURS = new Set([
+    "target-unstamped",
+    "target-other-organisation",
+    "target-owner-mismatch",
+    "reserved-fleet-scope",
+]);
+/**
+ * Keeps the rows that belong to the principal, deciding by STORED ID only.
+ * The ID-keyed replacement for the name-keyed `scopeFilterList`.
+ *
+ * Each row is judged by `assertTargetBelongsTo` (never re-derived here), so
+ * the same organisation, operator-org, unstamped, `ownerOnly` and
+ * `fleetCrossOrg` rules apply.
+ *
+ *   - The principal is proved FIRST, before any row is read. An absent or
+ *     unresolved principal, or a failed organisation-kind lookup for it,
+ *     returns `{ ok: false, refusal }` naming the door, even for an empty
+ *     list: a refusal is never an `ok: true` with no rows.
+ *   - `fleetCrossOrg: true` from a principal that is not `kind: "fleet"` is a
+ *     misconfigured door and is refused `reserved-fleet-scope` up front, for
+ *     any list. Per row, `reserved-fleet-scope` therefore only means "this row
+ *     is in the operator scope" and the row is dropped.
+ *   - A resolved principal whose rows all belong elsewhere gets
+ *     `{ ok: true, rows: [] }`: an absence, distinguishable from a refusal.
+ *   - A row that does not belong (other organisation, operator-org row,
+ *     unstamped, owner mismatch) is dropped. A same-NAME row of another
+ *     organisation is dropped: no name field is read.
+ *   - A lookup failure on any row refuses the whole call. It is never a
+ *     silent drop and never a pass; any refusal reason not known to mean
+ *     "this row is not yours" refuses too.
+ *   - The order of the kept rows is the order of the input.
+ */
+export async function filterTargetsBelongingTo(principal, rows, lookups, opts = {}) {
+    const door = opts.door ?? "filterTargetsBelongingTo";
+    const doorOpts = { ...opts, door };
+    // A door asking for cross-organisation reach that the principal does not
+    // hold is a misconfigured door: refused, never an absence of rows.
+    if (opts.fleetCrossOrg === true && principal != null && principal.kind !== "fleet") {
+        return denied("reserved-fleet-scope", door, "Cross-organisation reach is held only by the operator organisation's service account.");
+    }
+    // Prove the principal on a target that is its own organisation's, owner
+    // check off: only a principal-level fault can refuse this.
+    const proof = await assertTargetBelongsTo(principal, { orgId: principal?.orgId }, lookups, { ...doorOpts, ownerOnly: false, fleetCrossOrg: false });
+    if (!proof.ok)
+        return proof;
+    const kept = [];
+    for (const row of rows) {
+        const verdict = await assertTargetBelongsTo(principal, row, lookups, doorOpts);
+        if (verdict.ok) {
+            kept.push(row);
+        }
+        else if (!ROW_NOT_OURS.has(verdict.refusal.reason)) {
+            return verdict;
+        }
+    }
+    return { ok: true, rows: kept };
+}
 /**
  * Admits a principal as ADMIN of the target organisation, deciding by ID only.
  * The principal must come from `resolveActingPrincipal`; the role is the
@@ -438,4 +496,119 @@ export function assertPrincipalListed(principal, list, opts) {
     }
     return { ok: true };
 }
+/**
+ * Decides whether a sender may address a recipient, across organisations
+ * included, by AGENT ID only. The sender must come from
+ * `resolveActingPrincipal`. No name is read anywhere; a name never matches.
+ *
+ * Admitted iff one of these holds:
+ *   (a) same organisation: the sender's `orgId` equals the recipient's;
+ *   (b) client to operator: the sender is in a client organisation, the
+ *       recipient is in the operator organisation, and the RECIPIENT's ID is
+ *       on the SENDER organisation's roster;
+ *   (c) operator to client: the sender is in the operator organisation, the
+ *       recipient is in a client organisation, and the SENDER's ID is on the
+ *       RECIPIENT organisation's roster.
+ *
+ * Everything else is refused with a typed `RBAC_DENIED` carrying the door
+ * (default `"assertRecipientAddressable"`): an absent sender or one without an
+ * ID (`credential-invalid`), a sender that is not `kind: "agent"`
+ * (`principal-not-an-agent`), an absent recipient or one without an agent ID
+ * or organisation (`target-unstamped`), client to client across organisations
+ * and an organisation kind that is neither operator nor client
+ * (`target-other-organisation`), a missing or throwing `orgKindOf` /
+ * `rosterOf` (`principal-lookup-failed`), an absent roster (`list-absent`), and
+ * a roster that is empty, stored under the wrong organisation or does not list
+ * the ID (the refusals of {@link assertPrincipalListed}, which is reused for
+ * that check).
+ */
+export async function assertRecipientAddressable(sender, recipient, lookups, opts) {
+    const door = opts?.door ?? "assertRecipientAddressable";
+    if (sender === null ||
+        typeof sender !== "object" ||
+        !nonEmpty(sender.principalId) ||
+        !nonEmpty(sender.orgId)) {
+        return denied("credential-invalid", door, "No resolved sender stands behind this call.");
+    }
+    if (sender.kind !== "agent") {
+        return denied("principal-not-an-agent", door, "Only an agent addresses a recipient; the sender is not an agent.");
+    }
+    if (recipient === null ||
+        typeof recipient !== "object" ||
+        !nonEmpty(recipient.agentId) ||
+        !nonEmpty(recipient.orgId)) {
+        return denied("target-unstamped", door, "The recipient carries no agent ID and organisation.");
+    }
+    if (recipient.orgId === sender.orgId)
+        return { ok: true };
+    const senderKind = await loadOrgKind(lookups, sender.orgId, door);
+    if (!senderKind.ok)
+        return senderKind;
+    const recipientKind = await loadOrgKind(lookups, recipient.orgId, door);
+    if (!recipientKind.ok)
+        return recipientKind;
+    let clientOrgId;
+    let listed;
+    if (senderKind.kind === "client" && recipientKind.kind === "operator") {
+        clientOrgId = sender.orgId;
+        listed = { principalId: recipient.agentId };
+    }
+    else if (senderKind.kind === "operator" && recipientKind.kind === "client") {
+        clientOrgId = recipient.orgId;
+        listed = { principalId: sender.principalId };
+    }
+    else {
+        return denied("target-other-organisation", door, "The recipient belongs to another organisation that this sender may not reach.");
+    }
+    const rosterOf = lookups?.rosterOf;
+    if (typeof rosterOf !== "function") {
+        return denied("principal-lookup-failed", door, "No lookup was supplied for the roster.");
+    }
+    let roster;
+    try {
+        roster = await rosterOf(clientOrgId);
+    }
+    catch {
+        return denied("principal-lookup-failed", door, "The roster could not be read, so none is resolved.");
+    }
+    return assertPrincipalListed({ ...listed, orgId: clientOrgId, kind: "agent" }, roster, { door });
+}
+// ---------------------------------------------------------------------------
+// resolveCallerStanding (0.14.0)
+// ---------------------------------------------------------------------------
+/**
+ * A verified session that carries a person but NO organisation (a signed-in
+ * user who has not joined one). `resolveActingPrincipal` cannot express this:
+ * a person credential requires `verifiedOrgId`, so a no-organisation session
+ * is refused there exactly as a garbled credential is. This kind exists so
+ * the consumer can say "verified, and no organisation" on purpose; an absent
+ * `verifiedOrgId` on a `person` credential stays a garbled credential.
+ */
+const preOrgCredentialSchema = z.strictObject({
+    kind: z.literal("person-no-org"),
+    personId: z.string().min(1),
+});
+/**
+ * Derives a caller's STANDING from a verified credential. It adds one case to
+ * the existing primitives, the signed-in session with no organisation, and
+ * reuses them for everything else: `resolveActingPrincipal` decides who the
+ * caller is (and `fleet`), `assertOrgAdmin` decides `admin` against the
+ * principal's own organisation. Any other resolved principal (a person
+ * without the admin role, an agent, a non-operator service account) is a
+ * `member`; read `principal.kind` to tell them apart.
+ */
+export async function resolveCallerStanding(credential, lookups, opts) {
+    const door = opts?.door ?? "resolveCallerStanding";
+    const preOrg = preOrgCredentialSchema.safeParse(credential);
+    if (preOrg.success)
+        return { standing: "pre-org", personId: preOrg.data.personId };
+    const resolved = await resolveActingPrincipal(credential, lookups, door);
+    if (!resolved.ok)
+        return { standing: "anonymous", refusal: resolved.refusal };
+    const { principal } = resolved;
+    if (principal.kind === "fleet")
+        return { standing: "fleet", principal };
+    const admin = assertOrgAdmin(principal, principal.orgId, { adminRoles: opts?.adminRoles, door });
+    return { standing: admin.ok ? "admin" : "member", principal };
+}
 //# sourceMappingURL=principal-by-id.js.map