@objectstack/core 14.8.0 → 15.1.0

package/dist/index.d.cts

@@ -8,6 +8,7 @@ import { ConflictResolutionStrategy, ApiRegistryEntryInput, ApiRegistryEntry, Ap
 import * as QA from '@objectstack/spec/qa';
 import { KeyObject } from 'node:crypto';
 import { PluginCapability, PluginPermissions as PluginPermissions$1, PluginPermissionSet, ResourceType, PermissionAction, PluginPermission, SandboxConfig, KernelSecurityScanResult, KernelSecurityVulnerability, PluginHealthCheck, PluginHealthStatus as PluginHealthStatus$1, PluginHealthReport, HotReloadConfig, VersionConstraint, DependencyConflict, SemanticVersion, CompatibilityLevel } from '@objectstack/spec/kernel';
+import { AuthzPosture } from '@objectstack/spec/security';
 
 /**
  * Service Lifecycle Types
@@ -1739,6 +1740,16 @@ interface ResolvedAuthzContext {
     tabPermissions?: Record<string, 'visible' | 'hidden' | 'default_on' | 'default_off'>;
     /** Fellow-org user IDs for RLS scoping of identity tables (`id IN (...)`). */
     org_user_ids: string[];
+    /**
+     * [ADR-0095 D2/D3] The monotonic posture rung this principal resolves to,
+     * DERIVED once here from held capability grants (never a better-auth role):
+     * `PLATFORM_ADMIN` (unscoped `admin_full_access`) > `TENANT_ADMIN`
+     * (`organization_admin`) > `MEMBER` (the authenticated floor). `EXTERNAL` is
+     * defined/test-locked but never resolved yet (no external principal type —
+     * see `posture-ladder.ts`). Present only for an authenticated principal;
+     * anonymous requests carry no rung.
+     */
+    posture?: AuthzPosture;
 }
 interface ResolveAuthzInput {
     /** Data engine (ObjectQL) exposing `find(object, { where, limit, context })`. */
@@ -1778,6 +1789,111 @@ declare function resolveLocalizationContext(input: ResolveLocalizationInput): Pr
     currency?: string;
 }>;
 
+/**
+ * ── The monotonic posture ladder (ADR-0095 D2/D3) ───────────────────────────
+ *
+ * The principal-tiering enum resolved ONCE in `resolveAuthzContext`
+ * (`PLATFORM_ADMIN > TENANT_ADMIN > MEMBER > EXTERNAL`). This module owns two
+ * things and deliberately nothing more:
+ *
+ *  1. **Derivation (D3).** {@link derivePosture} maps held *capability grants*
+ *     — never a better-auth role — to a rung. `PLATFORM_ADMIN` derives from the
+ *     unscoped `admin_full_access` grant (the `viewAllRecords`/`modifyAllRecords`
+ *     evidence the superuser bypass already trusts); `TENANT_ADMIN` from the
+ *     `organization_admin` grant. The better-auth `role='admin'` is upstream a
+ *     *provisioning source* of those grants (`auto-org-admin-grant.ts`), so it
+ *     never re-enters adjudication here — the #2836 dual-track class is closed
+ *     by construction.
+ *
+ *  2. **The rung → injection-rule mapping + its tested invariants (D2).** Each
+ *     rung maps to EXACTLY ONE row-visibility injection rule
+ *     ({@link POSTURE_INJECTION_RULE}). {@link postureVisibleRows} is the
+ *     REFERENCE MODEL of those rules over a synthetic row-set — it locks the two
+ *     properties the ADR requires as invariants: strict nesting (rung n's
+ *     visible set ⊇ rung n−1's) and the EXTERNAL deny-by-default semantics
+ *     (explicit shares only, OWD never widens it).
+ *
+ * This module is NOT the enforcement path. The effective read/write filter is
+ * `Layer0(tenant) AND Layer1(business RLS)`, computed in `@objectstack/plugin-
+ * security` (`tenant-layer.ts` + `security-plugin.ts`), and the real behavior
+ * guard is the `authz-matrix-gate` unit snapshot + the dogfood conformance
+ * matrix. The reference model here exists so the ladder's *mathematical*
+ * properties can be asserted at the unit layer without an enforcement boot, and
+ * so the EXTERNAL rung — which has no enforcement path yet — cannot be
+ * reinvented differently when portal/external membership arrives.
+ */
+
+/**
+ * The rung ordering, high privilege → low, matching the spec enum's numeric
+ * values (`PLATFORM_ADMIN=3 … EXTERNAL=0`). Visibility grows monotonically UP
+ * this ladder (see {@link postureVisibleRows}).
+ */
+declare const POSTURE_LADDER: readonly ["PLATFORM_ADMIN", "TENANT_ADMIN", "MEMBER", "EXTERNAL"];
+/** Numeric rank per rung (mirrors the spec `AuthzPosture` enum values). */
+declare const POSTURE_RANK: Record<AuthzPosture, number>;
+/**
+ * The ONE row-visibility injection rule each rung maps to (ADR-0095 D2). Prose,
+ * because the machine artifacts live in enforcement (Layer 0 + the per-rung
+ * Layer 1 rule); this is the enumerable contract the explain track reports and
+ * {@link postureVisibleRows} models.
+ */
+declare const POSTURE_INJECTION_RULE: Record<AuthzPosture, string>;
+/** Capability-grant evidence the posture derivation consumes (ADR-0095 D3). */
+interface PostureEvidence {
+    /**
+     * Holds the UNSCOPED platform-admin capability grant (`admin_full_access` →
+     * `viewAllRecords`/`modifyAllRecords`) — the same evidence the superuser
+     * bypass trusts. NOT a better-auth role.
+     */
+    isPlatformAdmin: boolean;
+    /**
+     * Holds the org-admin capability grant (`organization_admin`, tenant-scoped
+     * `viewAllRecords`/`modifyAllRecords`). Provisioned from the better-auth
+     * owner/admin role upstream, consumed here only as a held capability.
+     */
+    isTenantAdmin: boolean;
+}
+/**
+ * Resolve the principal's posture rung from held capability grants (ADR-0095 D3).
+ *
+ * Returns `PLATFORM_ADMIN` | `TENANT_ADMIN` | `MEMBER`. It NEVER returns
+ * `EXTERNAL`: no external principal type exists yet (the sharing chain has no
+ * portal/guest-share concept — ADR-0095 W4). The `EXTERNAL` rung, its injection
+ * rule, and its semantics are defined and test-locked ({@link postureVisibleRows},
+ * {@link POSTURE_INJECTION_RULE}) so that when portal/external membership lands
+ * (ADR-0093) the derivation gains an EXTERNAL branch HERE without the rung being
+ * reinvented. `MEMBER` is the authenticated-principal floor.
+ */
+declare function derivePosture(evidence: PostureEvidence): AuthzPosture;
+/** A synthetic record for the ladder reference model. */
+interface LadderRow {
+    id: string;
+    /** The row's tenant. `undefined` = a non-tenant (platform-global) row. */
+    organization_id?: string;
+    /** The row's owner (drives the MEMBER ownership disjunct). */
+    owner_id?: string;
+    /**
+     * Whether an OWD-derived source would admit this row for a member (public
+     * baseline / criteria sharing). EXTERNAL deliberately ignores this field.
+     */
+    owdVisible?: boolean;
+    /** User ids this row is EXPLICITLY shared to (the only EXTERNAL source). */
+    sharedTo?: readonly string[];
+}
+/** The principal the reference model evaluates a rung for. */
+interface LadderPrincipal {
+    userId: string;
+    /** The principal's active organization (undefined for an unscoped principal). */
+    organizationId?: string;
+}
+/**
+ * Reference model of the per-rung injection rule: the visible-row set a rung
+ * would resolve to over `rows` for `principal`. Used to lock the ADR-0095 D2
+ * invariants (strict nesting + EXTERNAL deny-by-default). NOT an enforcement
+ * path — see the module header.
+ */
+declare function postureVisibleRows(posture: AuthzPosture, rows: readonly LadderRow[], principal: LadderPrincipal): LadderRow[];
+
 /**
  * ADR-0069 — authentication-policy session gate.
  *
@@ -1808,6 +1924,40 @@ declare function isAuthGateAllowlisted(rawPath: string | undefined | null): bool
  */
 declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
 
+/** HTTP status every seam returns for an anonymous-denied request. */
+declare const ANONYMOUS_DENY_STATUS: 401;
+/** Stable machine code (mirrors the REST `enforceAuth` seam). */
+declare const ANONYMOUS_DENY_CODE: "unauthenticated";
+/** Human-facing message. */
+declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
+/** The single 401 body shape every seam returns: `{ error, message }`. */
+declare const ANONYMOUS_DENY_BODY: {
+    readonly error: "unauthenticated";
+    readonly message: "Authentication is required to access this endpoint.";
+};
+interface AnonymousDenyInput {
+    /** The `requireAuth` posture. Falsy ⇒ no-op (demo / single-tenant). */
+    requireAuth: boolean | undefined;
+    /** Resolved caller id, if any. */
+    userId?: string | null;
+    /** Internal system context (never set on inbound HTTP; cannot be forged). */
+    isSystem?: boolean;
+    /** HTTP method — `OPTIONS` (CORS preflight) always passes. */
+    method?: string | null;
+    /**
+     * OPTIONAL request path. When a NON-EMPTY string, a control-plane path
+     * (auth / health / ready / discovery — see {@link isAuthGateAllowlisted}) is
+     * exempt. Body-routed seams (GraphQL) have no meaningful path and pass
+     * `undefined`; see the guard below for why that is load-bearing.
+     */
+    path?: string | null;
+}
+/**
+ * True when the request MUST be rejected with 401. The one decision every HTTP
+ * seam shares.
+ */
+declare function shouldDenyAnonymous(input: AnonymousDenyInput): boolean;
+
 /** The validity-window shape shared by both user-grant tables (ADR-0091 D1). */
 interface GrantValidityWindow {
     valid_from?: unknown;
@@ -2394,4 +2544,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry };
+export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, type AnonymousDenyInput, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, postureVisibleRows, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, shouldDenyAnonymous, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry };

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { ConflictResolutionStrategy, ApiRegistryEntryInput, ApiRegistryEntry, Ap
 import * as QA from '@objectstack/spec/qa';
 import { KeyObject } from 'node:crypto';
 import { PluginCapability, PluginPermissions as PluginPermissions$1, PluginPermissionSet, ResourceType, PermissionAction, PluginPermission, SandboxConfig, KernelSecurityScanResult, KernelSecurityVulnerability, PluginHealthCheck, PluginHealthStatus as PluginHealthStatus$1, PluginHealthReport, HotReloadConfig, VersionConstraint, DependencyConflict, SemanticVersion, CompatibilityLevel } from '@objectstack/spec/kernel';
+import { AuthzPosture } from '@objectstack/spec/security';
 
 /**
  * Service Lifecycle Types
@@ -1739,6 +1740,16 @@ interface ResolvedAuthzContext {
     tabPermissions?: Record<string, 'visible' | 'hidden' | 'default_on' | 'default_off'>;
     /** Fellow-org user IDs for RLS scoping of identity tables (`id IN (...)`). */
     org_user_ids: string[];
+    /**
+     * [ADR-0095 D2/D3] The monotonic posture rung this principal resolves to,
+     * DERIVED once here from held capability grants (never a better-auth role):
+     * `PLATFORM_ADMIN` (unscoped `admin_full_access`) > `TENANT_ADMIN`
+     * (`organization_admin`) > `MEMBER` (the authenticated floor). `EXTERNAL` is
+     * defined/test-locked but never resolved yet (no external principal type —
+     * see `posture-ladder.ts`). Present only for an authenticated principal;
+     * anonymous requests carry no rung.
+     */
+    posture?: AuthzPosture;
 }
 interface ResolveAuthzInput {
     /** Data engine (ObjectQL) exposing `find(object, { where, limit, context })`. */
@@ -1778,6 +1789,111 @@ declare function resolveLocalizationContext(input: ResolveLocalizationInput): Pr
     currency?: string;
 }>;
 
+/**
+ * ── The monotonic posture ladder (ADR-0095 D2/D3) ───────────────────────────
+ *
+ * The principal-tiering enum resolved ONCE in `resolveAuthzContext`
+ * (`PLATFORM_ADMIN > TENANT_ADMIN > MEMBER > EXTERNAL`). This module owns two
+ * things and deliberately nothing more:
+ *
+ *  1. **Derivation (D3).** {@link derivePosture} maps held *capability grants*
+ *     — never a better-auth role — to a rung. `PLATFORM_ADMIN` derives from the
+ *     unscoped `admin_full_access` grant (the `viewAllRecords`/`modifyAllRecords`
+ *     evidence the superuser bypass already trusts); `TENANT_ADMIN` from the
+ *     `organization_admin` grant. The better-auth `role='admin'` is upstream a
+ *     *provisioning source* of those grants (`auto-org-admin-grant.ts`), so it
+ *     never re-enters adjudication here — the #2836 dual-track class is closed
+ *     by construction.
+ *
+ *  2. **The rung → injection-rule mapping + its tested invariants (D2).** Each
+ *     rung maps to EXACTLY ONE row-visibility injection rule
+ *     ({@link POSTURE_INJECTION_RULE}). {@link postureVisibleRows} is the
+ *     REFERENCE MODEL of those rules over a synthetic row-set — it locks the two
+ *     properties the ADR requires as invariants: strict nesting (rung n's
+ *     visible set ⊇ rung n−1's) and the EXTERNAL deny-by-default semantics
+ *     (explicit shares only, OWD never widens it).
+ *
+ * This module is NOT the enforcement path. The effective read/write filter is
+ * `Layer0(tenant) AND Layer1(business RLS)`, computed in `@objectstack/plugin-
+ * security` (`tenant-layer.ts` + `security-plugin.ts`), and the real behavior
+ * guard is the `authz-matrix-gate` unit snapshot + the dogfood conformance
+ * matrix. The reference model here exists so the ladder's *mathematical*
+ * properties can be asserted at the unit layer without an enforcement boot, and
+ * so the EXTERNAL rung — which has no enforcement path yet — cannot be
+ * reinvented differently when portal/external membership arrives.
+ */
+
+/**
+ * The rung ordering, high privilege → low, matching the spec enum's numeric
+ * values (`PLATFORM_ADMIN=3 … EXTERNAL=0`). Visibility grows monotonically UP
+ * this ladder (see {@link postureVisibleRows}).
+ */
+declare const POSTURE_LADDER: readonly ["PLATFORM_ADMIN", "TENANT_ADMIN", "MEMBER", "EXTERNAL"];
+/** Numeric rank per rung (mirrors the spec `AuthzPosture` enum values). */
+declare const POSTURE_RANK: Record<AuthzPosture, number>;
+/**
+ * The ONE row-visibility injection rule each rung maps to (ADR-0095 D2). Prose,
+ * because the machine artifacts live in enforcement (Layer 0 + the per-rung
+ * Layer 1 rule); this is the enumerable contract the explain track reports and
+ * {@link postureVisibleRows} models.
+ */
+declare const POSTURE_INJECTION_RULE: Record<AuthzPosture, string>;
+/** Capability-grant evidence the posture derivation consumes (ADR-0095 D3). */
+interface PostureEvidence {
+    /**
+     * Holds the UNSCOPED platform-admin capability grant (`admin_full_access` →
+     * `viewAllRecords`/`modifyAllRecords`) — the same evidence the superuser
+     * bypass trusts. NOT a better-auth role.
+     */
+    isPlatformAdmin: boolean;
+    /**
+     * Holds the org-admin capability grant (`organization_admin`, tenant-scoped
+     * `viewAllRecords`/`modifyAllRecords`). Provisioned from the better-auth
+     * owner/admin role upstream, consumed here only as a held capability.
+     */
+    isTenantAdmin: boolean;
+}
+/**
+ * Resolve the principal's posture rung from held capability grants (ADR-0095 D3).
+ *
+ * Returns `PLATFORM_ADMIN` | `TENANT_ADMIN` | `MEMBER`. It NEVER returns
+ * `EXTERNAL`: no external principal type exists yet (the sharing chain has no
+ * portal/guest-share concept — ADR-0095 W4). The `EXTERNAL` rung, its injection
+ * rule, and its semantics are defined and test-locked ({@link postureVisibleRows},
+ * {@link POSTURE_INJECTION_RULE}) so that when portal/external membership lands
+ * (ADR-0093) the derivation gains an EXTERNAL branch HERE without the rung being
+ * reinvented. `MEMBER` is the authenticated-principal floor.
+ */
+declare function derivePosture(evidence: PostureEvidence): AuthzPosture;
+/** A synthetic record for the ladder reference model. */
+interface LadderRow {
+    id: string;
+    /** The row's tenant. `undefined` = a non-tenant (platform-global) row. */
+    organization_id?: string;
+    /** The row's owner (drives the MEMBER ownership disjunct). */
+    owner_id?: string;
+    /**
+     * Whether an OWD-derived source would admit this row for a member (public
+     * baseline / criteria sharing). EXTERNAL deliberately ignores this field.
+     */
+    owdVisible?: boolean;
+    /** User ids this row is EXPLICITLY shared to (the only EXTERNAL source). */
+    sharedTo?: readonly string[];
+}
+/** The principal the reference model evaluates a rung for. */
+interface LadderPrincipal {
+    userId: string;
+    /** The principal's active organization (undefined for an unscoped principal). */
+    organizationId?: string;
+}
+/**
+ * Reference model of the per-rung injection rule: the visible-row set a rung
+ * would resolve to over `rows` for `principal`. Used to lock the ADR-0095 D2
+ * invariants (strict nesting + EXTERNAL deny-by-default). NOT an enforcement
+ * path — see the module header.
+ */
+declare function postureVisibleRows(posture: AuthzPosture, rows: readonly LadderRow[], principal: LadderPrincipal): LadderRow[];
+
 /**
  * ADR-0069 — authentication-policy session gate.
  *
@@ -1808,6 +1924,40 @@ declare function isAuthGateAllowlisted(rawPath: string | undefined | null): bool
  */
 declare function evaluateAuthGate(sessionUser: any, path: string): AuthGate | null;
 
+/** HTTP status every seam returns for an anonymous-denied request. */
+declare const ANONYMOUS_DENY_STATUS: 401;
+/** Stable machine code (mirrors the REST `enforceAuth` seam). */
+declare const ANONYMOUS_DENY_CODE: "unauthenticated";
+/** Human-facing message. */
+declare const ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
+/** The single 401 body shape every seam returns: `{ error, message }`. */
+declare const ANONYMOUS_DENY_BODY: {
+    readonly error: "unauthenticated";
+    readonly message: "Authentication is required to access this endpoint.";
+};
+interface AnonymousDenyInput {
+    /** The `requireAuth` posture. Falsy ⇒ no-op (demo / single-tenant). */
+    requireAuth: boolean | undefined;
+    /** Resolved caller id, if any. */
+    userId?: string | null;
+    /** Internal system context (never set on inbound HTTP; cannot be forged). */
+    isSystem?: boolean;
+    /** HTTP method — `OPTIONS` (CORS preflight) always passes. */
+    method?: string | null;
+    /**
+     * OPTIONAL request path. When a NON-EMPTY string, a control-plane path
+     * (auth / health / ready / discovery — see {@link isAuthGateAllowlisted}) is
+     * exempt. Body-routed seams (GraphQL) have no meaningful path and pass
+     * `undefined`; see the guard below for why that is load-bearing.
+     */
+    path?: string | null;
+}
+/**
+ * True when the request MUST be rejected with 401. The one decision every HTTP
+ * seam shares.
+ */
+declare function shouldDenyAnonymous(input: AnonymousDenyInput): boolean;
+
 /** The validity-window shape shared by both user-grant tables (ADR-0091 D1). */
 interface GrantValidityWindow {
     valid_from?: unknown;
@@ -2394,4 +2544,4 @@ declare class NamespaceResolver {
     private suggestAlternative;
 }
 
-export { API_KEY_PREFIX, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type KernelState, type KeyInput, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry };
+export { ANONYMOUS_DENY_BODY, ANONYMOUS_DENY_CODE, ANONYMOUS_DENY_MESSAGE, ANONYMOUS_DENY_STATUS, API_KEY_PREFIX, type AnonymousDenyInput, type ApiKeyPrincipal, ApiRegistry, type ApiRegistryPluginConfig, type AuthGate, type BulkWriteOptions, type BulkWriteRowResult, CORE_FALLBACK_FACTORIES, type CalendarParts, DependencyResolver, type GeneratedApiKey, type GrantValidityWindow, HotReloadManager, type KernelState, type KeyInput, type LadderPrincipal, type LadderRow, LiteKernel, type NamespaceCheckResult, type NamespaceConflict, type NamespaceEntry, NamespaceResolver, ObjectKernel, ObjectKernelBase, type ObjectKernelConfig, ObjectLogger, POSTURE_INJECTION_RULE, POSTURE_LADDER, POSTURE_RANK, type ParsedSignature, type PermissionCheckResult$1 as PermissionCheckResult, type PermissionGrant, type Plugin, type PluginArtifactVerifyResult, PluginConfigValidator, type PluginContext, PluginHealthMonitor, type PluginHealthStatus, type PluginLoadResult, PluginLoader, type PluginMetadata, type PermissionCheckResult as PluginPermissionCheckResult, PluginPermissionEnforcer, PluginPermissionManager, type PluginPermissions, PluginSandboxRuntime, PluginSecurityScanner, type PluginSignatureConfig, PluginSignatureVerifier, type PluginStartupResult, type PostureEvidence, type PublisherVerifyResult, index as QA, type ResolveAuthzInput, type ResolveLocalizationInput, type ResolvedAuthzContext, type ResourceUsage, type RetryOptions, SIGNATURE_ALG, type SandboxContext, type ScanTarget, SecurePluginContext, type SecurityIssue, SemanticVersionManager, type ServiceFactory, ServiceLifecycle, type ServiceRegistration, type SignatureVerificationResult, type VersionCompatibility, buildPermissionsFromGrants, bulkWrite, calendarPartsInTz, calendarPartsInTzOrUtc, counterSignPayload, createApiRegistryPlugin, createMemoryCache, createMemoryI18n, createMemoryJob, createMemoryMetadata, createMemoryQueue, createPluginConfigValidator, createPluginPermissionEnforcer, deepMerge, defaultIsTransientError, derivePosture, evaluateAuthGate, extractApiKey, generateApiKey, generateEd25519KeyPair, getEnv, getMemoryUsage, hashApiKey, isAuthGateAllowlisted, isExpired, isGrantActive, isGrantExpired, isNode, parseScopes, parseSignature, postureVisibleRows, readAuthoredTranslationLayer, resolveApiKeyPrincipal, resolveAuthzContext, resolveLocale, resolveLocalizationContext, safeExit, shouldDenyAnonymous, signPayload, verifyPayload, verifyPlatformSignature, verifyPluginArtifact, verifyPublisherSignature, wireAuthoredTranslationSync, withTransientRetry };

package/dist/index.js

@@ -1554,6 +1554,8 @@ var ObjectKernel = class {
       this.validateSystemRequirements();
       this.logger.debug("Triggering kernel:ready hook");
       await this.context.trigger("kernel:ready");
+      this.logger.debug("Triggering kernel:bootstrapped hook");
+      await this.context.trigger("kernel:bootstrapped");
       this.logger.debug("Triggering kernel:listening hook");
       await this.context.trigger("kernel:listening");
       this.logger.info("\u2705 Bootstrap complete");
@@ -1837,6 +1839,7 @@ var LiteKernel = class extends ObjectKernelBase {
       await this.runPluginStart(plugin);
     }
     await this.triggerHook("kernel:ready");
+    await this.triggerHook("kernel:bootstrapped");
     await this.triggerHook("kernel:listening");
     this.logger.info("\u2705 Bootstrap complete", {
       pluginCount: this.plugins.size
@@ -4136,7 +4139,8 @@ function safeJsonParse(s, fallback) {
 import {
   mapMembershipRole,
   BUILTIN_IDENTITY_PLATFORM_ADMIN,
-  ADMIN_FULL_ACCESS
+  ADMIN_FULL_ACCESS,
+  ORGANIZATION_ADMIN
 } from "@objectstack/spec";
 
 // src/security/grant-validity.ts
@@ -4164,6 +4168,62 @@ function isGrantExpired(row, nowMs) {
   return !(nowMs < until);
 }
 
+// src/security/posture-ladder.ts
+var POSTURE_LADDER = [
+  "PLATFORM_ADMIN",
+  "TENANT_ADMIN",
+  "MEMBER",
+  "EXTERNAL"
+];
+var POSTURE_RANK = {
+  PLATFORM_ADMIN: 3,
+  TENANT_ADMIN: 2,
+  MEMBER: 1,
+  EXTERNAL: 0
+};
+var POSTURE_INJECTION_RULE = {
+  PLATFORM_ADMIN: "Layer 0 exemption where the object posture permits (private / platform-global / better-auth-managed) \u2014 crosses the tenant wall; org-scoped like TENANT_ADMIN on ordinary tenant business objects.",
+  TENANT_ADMIN: "All rows within the active organization (organization_id == ctx.tenantId); no ownership / depth / sharing narrowing.",
+  MEMBER: "Business RLS within the organization \u2014 ownership (owner / unit depth), the OWD baseline, and explicit sharing.",
+  EXTERNAL: "Explicitly shared rows ONLY \u2014 OWD baselines and sharing rules never apply; a misconfiguration can only shrink visibility, never widen it."
+};
+function derivePosture(evidence) {
+  if (evidence.isPlatformAdmin) return "PLATFORM_ADMIN";
+  if (evidence.isTenantAdmin) return "TENANT_ADMIN";
+  return "MEMBER";
+}
+function isSharedTo(row, userId) {
+  return (row.sharedTo ?? []).includes(userId);
+}
+function externalVisible(rows, p) {
+  return rows.filter((r) => isSharedTo(r, p.userId));
+}
+function memberVisible(rows, p) {
+  const shared = new Set(externalVisible(rows, p));
+  return rows.filter(
+    (r) => shared.has(r) || r.organization_id === p.organizationId && (r.owner_id === p.userId || r.owdVisible === true)
+  );
+}
+function tenantAdminVisible(rows, p) {
+  const member = new Set(memberVisible(rows, p));
+  return rows.filter((r) => member.has(r) || r.organization_id === p.organizationId);
+}
+function platformAdminVisible(rows) {
+  return [...rows];
+}
+function postureVisibleRows(posture, rows, principal) {
+  switch (posture) {
+    case "PLATFORM_ADMIN":
+      return platformAdminVisible(rows);
+    case "TENANT_ADMIN":
+      return tenantAdminVisible(rows, principal);
+    case "MEMBER":
+      return memberVisible(rows, principal);
+    case "EXTERNAL":
+      return externalVisible(rows, principal);
+  }
+}
+
 // src/security/resolve-authz-context.ts
 function safeJsonParse2(s, fallback) {
   try {
@@ -4310,6 +4370,10 @@ async function resolveAuthzContext(input) {
   if (hasPlatformAdminGrant && !ctx.positions.includes(BUILTIN_IDENTITY_PLATFORM_ADMIN)) {
     ctx.positions.unshift(BUILTIN_IDENTITY_PLATFORM_ADMIN);
   }
+  ctx.posture = derivePosture({
+    isPlatformAdmin: hasPlatformAdminGrant,
+    isTenantAdmin: ctx.permissions.includes(ORGANIZATION_ADMIN)
+  });
   if (!ctx.permissions.includes("ai_seat")) {
     const aiAccess = (await getUserRow())?.ai_access;
     if (aiAccess === true || aiAccess === 1 || aiAccess === "1") ctx.permissions.push("ai_seat");
@@ -4395,6 +4459,26 @@ function evaluateAuthGate(sessionUser, path) {
   };
 }
 
+// src/security/anonymous-deny.ts
+var ANONYMOUS_DENY_STATUS = 401;
+var ANONYMOUS_DENY_CODE = "unauthenticated";
+var ANONYMOUS_DENY_MESSAGE = "Authentication is required to access this endpoint.";
+var ANONYMOUS_DENY_BODY = {
+  error: ANONYMOUS_DENY_CODE,
+  message: ANONYMOUS_DENY_MESSAGE
+};
+function shouldDenyAnonymous(input) {
+  if (!input.requireAuth) return false;
+  if (typeof input.method === "string" && input.method.toUpperCase() === "OPTIONS") {
+    return false;
+  }
+  if (input.userId || input.isSystem) return false;
+  if (typeof input.path === "string" && input.path.length > 0 && isAuthGateAllowlisted(input.path)) {
+    return false;
+  }
+  return true;
+}
+
 // src/utils/datetime.ts
 function calendarPartsInTz(d, tz) {
   const parts = new Intl.DateTimeFormat("en-US", {
@@ -5415,6 +5499,10 @@ var NamespaceResolver = class {
   }
 };
 export {
+  ANONYMOUS_DENY_BODY,
+  ANONYMOUS_DENY_CODE,
+  ANONYMOUS_DENY_MESSAGE,
+  ANONYMOUS_DENY_STATUS,
   API_KEY_PREFIX,
   ApiRegistry,
   CORE_FALLBACK_FACTORIES,
@@ -5425,6 +5513,9 @@ export {
   ObjectKernel,
   ObjectKernelBase,
   ObjectLogger,
+  POSTURE_INJECTION_RULE,
+  POSTURE_LADDER,
+  POSTURE_RANK,
   PluginConfigValidator,
   PluginHealthMonitor,
   PluginLoader,
@@ -5454,6 +5545,7 @@ export {
   createPluginPermissionEnforcer,
   deepMerge,
   defaultIsTransientError,
+  derivePosture,
   evaluateAuthGate,
   extractApiKey,
   generateApiKey,
@@ -5468,12 +5560,14 @@ export {
   isNode,
   parseScopes,
   parseSignature,
+  postureVisibleRows,
   readAuthoredTranslationLayer,
   resolveApiKeyPrincipal,
   resolveAuthzContext,
   resolveLocale,
   resolveLocalizationContext,
   safeExit,
+  shouldDenyAnonymous,
   signPayload,
   verifyPayload,
   verifyPlatformSignature,