@consciousclouds/access 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@consciousclouds/access` are documented here.
+
+## 0.1.0
+
+- Initial release. The policy-free Access SDK for the Control Plane's operator
+  identity + Access surface (control-plane-doctrine §5, Build Increment 1).
+- Four subpath exports: root (types) · `/client` (isomorphic no-store HTTP
+  wrappers) · `/server` (request-bound, fail-closed BFF adapter) · `/react`
+  (`AccessProvider` + operator hooks, including the
+  `useOperatorPermissionResolver` bridge).
+- Reuses the `Capability` `<primitive>.<verb>` vocabulary and the operator-shell
+  `allowed|denied|unknown` decision union (`unknown` ⇒ denied).
+- First consumer: the CCU Admin migration off the dev-auth stub onto the real
+  Control Plane.

package/LICENSE

@@ -0,0 +1,171 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one of the
+          following places: within a NOTICE text provided as part of the
+          Derivative Works; within the Source form or documentation, if
+          provided along with the Derivative Works; or, within a display
+          generated by the Derivative Works, if and wherever such third-party
+          notices normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or in addition to the NOTICE text from the
+          Work, provided that such additional attribution notices cannot be
+          construed as modifying the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      MERCHANTIBILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+      responsible for determining the appropriateness of using or
+      redistributing the Work and assume any risks associated with Your
+      exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a result
+      of this License or out of the use or inability to use the Work
+      (including but not limited to damages for loss of goodwill, work
+      stoppage, computer failure or malfunction, or all other commercial
+      damages or losses), even if such Contributor has been advised of the
+      possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend, and
+      hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   Copyright 2024 Conscious Clouds
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,49 @@
+# @consciousclouds/access
+
+The thin, **policy-free** client for the Control Plane's operator identity +
+Access surface — the SDK half of *"central authority, local enforcement"*
+([control-plane-doctrine](../../../docs/design/control-plane-doctrine.md) §5).
+
+The Control Plane **decides**; this SDK only asks the five operating questions
+and **enforces the answers, fail-closed**:
+
+> *Who is the current operator? What project is being entered? What permissions
+> does this operator have here? Can this action be performed? What capabilities
+> are granted?*
+
+**No policy logic.** Types + thin HTTP wrappers + React/server wiring only. There
+is no role→capability mapping, no grant cache, no second permission vocabulary —
+it reuses the `Capability` `<primitive>.<verb>` type from
+`@consciousclouds/capability-sdk` and the operator-shell's `allowed|denied|unknown`
+decision union (`unknown` ⇒ denied).
+
+## Exports
+
+| Subpath | What | Runs |
+|---|---|---|
+| `.` | Types only — `OperatorIdentity`, `ProjectScope`, `Grant`, `AccessDecision`, `AccessIntent`, `AccessSession`, `PermissionResolver` | anywhere |
+| `./client` | `createAccessClient({ baseUrl })` → `login` · `refresh` · `logout` · `whoami` · `session` · `can`. Isomorphic, every call `cache: 'no-store'`, holds no grant cache | where the token is readable |
+| `./server` | `createAccess({ baseUrl, cookieName, scope, capabilities })` → request-bound `identity` · `scope` · `session` · `can`. **Fail-closed** (deny / unreachable / throw ⇒ denied) | server (BFF / RSC) |
+| `./react` | `AccessProvider` + `useOperator` · `useProjectScope` · `useGrants` · `useCapabilities` · `useCan` · `useOperatorPermissionResolver` | client |
+
+## The grant-resolution note
+
+`GET /access/session` returns the operator's **role** assignments, not resolved
+`<primitive>.<verb>` capabilities. The only path to a capability decision is
+`POST /access/authorize`. So `AccessSession.grants` (the capability set the UI
+gates on) is assembled by asking the Control Plane's authorize decision for a
+**candidate** capability set — a policy-free aggregation (the Control Plane
+decides each one). The candidate set is the capabilities a surface gates its nav
+on (e.g. `factory.observe`).
+
+## The load-bearing rule
+
+`access.can(scope, action)` server-side, **uncached, fail-closed** — before any
+admin read or token-spending turn is forwarded. A hidden nav item is never the
+enforcement; the server call is.
+
+## Adopting it for a second surface
+
+Two adapters from the standard template — an identity adapter (its cookie name,
+login endpoint, issuer/audience) and an access adapter (its `scope`, its BFF
+routes) — plus the product's Brand + Flavor. No shell fork, no SDK fork.

package/dist/client/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `@consciousclouds/access/client` — isomorphic, no-store HTTP wrappers over the
+ * Control Plane's operator-identity + Access surface. Thin by contract: parse
+ * the request, call the endpoint, shape the response. NO policy, NO grant cache
+ * (every call is `cache: 'no-store'`; the Control Plane is the only authority).
+ *
+ * These wrappers take an explicit operator `token` — they are meant to run where
+ * the token is readable (the BFF `/server` adapter, a login route). The browser
+ * never holds the operator token (it lives in an httpOnly cookie); browser code
+ * goes through the product's same-origin BFF routes and the `/react` hooks.
+ */
+import type { AccessDecision, AccessIntent, AccessSession, Grant, OperatorIdentity, ProjectScope } from '../types.js';
+/** Configuration for a client bound to one Control Plane origin. */
+export interface AccessClientConfig {
+    /** The Control Plane base URL (server-only; never a `NEXT_PUBLIC_` value). */
+    baseUrl: string;
+    /** Optional fetch implementation (defaults to the ambient global `fetch`). */
+    fetchImpl?: typeof fetch;
+    /** Default freshness window the assembled AccessSession advertises. */
+    ttlSeconds?: number;
+}
+/** The credential a login accepts. Operators only — no product-user path exists. */
+export interface LoginInput {
+    email: string;
+    password: string;
+}
+/** The token bundle the Control Plane returns from login/refresh (snake_case wire → camelCase). */
+export interface TokenSet {
+    accessToken: string;
+    refreshToken: string;
+    sid: string;
+    operatorId: string;
+    /** Access-token lifetime in seconds (~15m). */
+    expiresIn: number;
+    tokenType: string;
+}
+/** An error carrying the HTTP status so callers can distinguish 401 from unreachable. */
+export declare class AccessError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, message: string, code?: string);
+}
+/** Build the display identity from an access token's claims (null if malformed). */
+export declare function identityFromToken(token: string | null | undefined): OperatorIdentity | null;
+/** A client bound to one Control Plane origin. */
+export interface AccessClient {
+    login(input: LoginInput): Promise<TokenSet>;
+    refresh(refreshToken: string): Promise<TokenSet>;
+    logout(token: string): Promise<void>;
+    whoami(token: string): Promise<OperatorIdentity | null>;
+    session(token: string, scope: ProjectScope, candidates?: readonly Grant[]): Promise<AccessSession>;
+    can(token: string, scope: ProjectScope, action: Grant, intent?: AccessIntent): Promise<AccessDecision>;
+}
+/** Create a client bound to one Control Plane origin. */
+export declare function createAccessClient(config: AccessClientConfig): AccessClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,aAAa,EACb,KAAK,EACL,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mGAAmG;AACnG,MAAM,WAAW,QAAQ;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM3D;AA0BD,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAW3F;AAuBD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,SAAS,KAAK,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACxG;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CA8H3E"}

package/dist/client/index.js

@@ -0,0 +1,178 @@
+/**
+ * `@consciousclouds/access/client` — isomorphic, no-store HTTP wrappers over the
+ * Control Plane's operator-identity + Access surface. Thin by contract: parse
+ * the request, call the endpoint, shape the response. NO policy, NO grant cache
+ * (every call is `cache: 'no-store'`; the Control Plane is the only authority).
+ *
+ * These wrappers take an explicit operator `token` — they are meant to run where
+ * the token is readable (the BFF `/server` adapter, a login route). The browser
+ * never holds the operator token (it lives in an httpOnly cookie); browser code
+ * goes through the product's same-origin BFF routes and the `/react` hooks.
+ */
+/** An error carrying the HTTP status so callers can distinguish 401 from unreachable. */
+export class AccessError extends Error {
+    constructor(status, message, code) {
+        super(message);
+        this.name = 'AccessError';
+        this.status = status;
+        this.code = code;
+    }
+}
+const DEFAULT_TTL_SECONDS = 30;
+/** Decode a JWT's claims for DISPLAY only (no verification). Isomorphic (atob, no Buffer). */
+function decodeClaims(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+        const json = decodeURIComponent(Array.prototype.map
+            .call(atob(b64 + pad), (c) => '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2))
+            .join(''));
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** Build the display identity from an access token's claims (null if malformed). */
+export function identityFromToken(token) {
+    if (!token)
+        return null;
+    const claims = decodeClaims(token);
+    if (!claims || !str(claims.sub))
+        return null;
+    return {
+        sub: str(claims.sub),
+        email: str(claims.email),
+        iss: str(claims.iss),
+        aud: str(claims.aud),
+        exp: typeof claims.exp === 'number' ? claims.exp : undefined,
+    };
+}
+/** Extract the (sub, sid) an Access call needs from a verified token's claims. */
+function principalFromToken(token) {
+    const claims = decodeClaims(token) ?? {};
+    return { sub: str(claims.sub), sid: str(claims.sid) };
+}
+/** Create a client bound to one Control Plane origin. */
+export function createAccessClient(config) {
+    const doFetch = config.fetchImpl ?? fetch;
+    const base = config.baseUrl.replace(/\/$/, '');
+    const ttlSeconds = config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    function tokenSetFrom(body) {
+        return {
+            accessToken: str(body.access_token),
+            refreshToken: str(body.refresh_token),
+            sid: str(body.sid),
+            operatorId: str(body.operator_id),
+            expiresIn: typeof body.expires_in === 'number' ? body.expires_in : 0,
+            tokenType: str(body.token_type) || 'Bearer',
+        };
+    }
+    async function login(input) {
+        const res = await doFetch(`${base}/operator/login`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email: input.email, password: input.password }),
+            cache: 'no-store',
+        });
+        if (!res.ok) {
+            const detail = (await res.json().catch(() => ({})));
+            throw new AccessError(res.status, detail.error?.message ?? `login failed (${res.status})`, detail.error?.code);
+        }
+        return tokenSetFrom((await res.json()));
+    }
+    async function refresh(refreshToken) {
+        const res = await doFetch(`${base}/operator/refresh`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refresh_token: refreshToken }),
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            throw new AccessError(res.status, `refresh failed (${res.status})`);
+        return tokenSetFrom((await res.json()));
+    }
+    async function logout(token) {
+        await doFetch(`${base}/operator/logout`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}` },
+            cache: 'no-store',
+        });
+    }
+    async function whoami(token) {
+        const fromToken = identityFromToken(token);
+        if (!fromToken)
+            return null;
+        const res = await doFetch(`${base}/operator/me`, {
+            headers: { Authorization: `Bearer ${token}` },
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            return fromToken;
+        const body = (await res.json().catch(() => ({})));
+        return {
+            ...fromToken,
+            email: str(body.email) || fromToken.email,
+            displayName: str(body.display_name) || undefined,
+        };
+    }
+    async function can(token, scope, action, intent = 'mutate') {
+        const { sub, sid } = principalFromToken(token);
+        if (!sub || !sid)
+            return 'denied';
+        // Send the bearer so an edge-authed ingress (the Operator Gateway) verifies the operator; the
+        // (operator_sub, sid) body stays the Control Plane's S2S proof (defense in depth — the CP re-proves).
+        const res = await doFetch(`${base}/access/authorize`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify({
+                operator_sub: sub,
+                sid,
+                action,
+                project: scope.project,
+                intent,
+            }),
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            return 'denied';
+        const body = (await res.json().catch(() => ({})));
+        return body.allowed === true ? 'allowed' : 'denied';
+    }
+    async function session(token, scope, candidates = []) {
+        const identity = identityFromToken(token);
+        const empty = { identity, scope, roles: [], grants: [], ttlSeconds };
+        const { sub, sid } = principalFromToken(token);
+        if (!sub || !sid)
+            return empty;
+        const url = `${base}/access/session?operator_sub=${encodeURIComponent(sub)}&sid=${encodeURIComponent(sid)}&project=${encodeURIComponent(scope.project)}`;
+        // Bearer for the edge-authed ingress; the (operator_sub, sid) query stays the CP's S2S proof.
+        const res = await doFetch(url, { cache: 'no-store', headers: { Authorization: `Bearer ${token}` } });
+        if (!res.ok)
+            return empty;
+        const body = (await res.json().catch(() => ({})));
+        if (!body.live)
+            return empty;
+        const roles = Array.from(new Set((body.grants ?? []).map((g) => g.role).filter(Boolean)));
+        // The session endpoint returns ROLES, not resolved capabilities. Resolve the
+        // granted subset by asking the Control Plane's authorize decision for each
+        // candidate capability — policy-free aggregation (the Control Plane decides
+        // each one). A candidate is `read` unless it declares mutate semantics; we
+        // probe with `read` so a read-only operator's read capabilities resolve.
+        const grants = [];
+        for (const action of candidates) {
+            const decision = await can(token, scope, action, 'read').catch(() => 'denied');
+            if (decision === 'allowed')
+                grants.push(action);
+        }
+        return { identity, scope, roles, grants, ttlSeconds };
+    }
+    return { login, refresh, logout, whoami, session, can };
+}
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@consciousclouds/access` — root export: TYPES ONLY.
+ *
+ * The thin, policy-free client for the Control Plane's operator identity +
+ * Access surface. Import the runtime pieces from the subpaths:
+ *   - `@consciousclouds/access/client` — isomorphic no-store HTTP wrappers.
+ *   - `@consciousclouds/access/server` — request-bound, fail-closed BFF adapter.
+ *   - `@consciousclouds/access/react`  — AccessProvider + hooks.
+ *
+ * This package carries NO policy logic. Every access decision belongs to the
+ * Control Plane (control-plane-doctrine §5); the SDK only asks the five
+ * operating questions and enforces the answers, fail-closed.
+ */
+export type { OperatorIdentity, ProjectScope, Grant, AccessDecision, AccessIntent, AccessSession, PermissionResolver, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@consciousclouds/access` — root export: TYPES ONLY.
+ *
+ * The thin, policy-free client for the Control Plane's operator identity +
+ * Access surface. Import the runtime pieces from the subpaths:
+ *   - `@consciousclouds/access/client` — isomorphic no-store HTTP wrappers.
+ *   - `@consciousclouds/access/server` — request-bound, fail-closed BFF adapter.
+ *   - `@consciousclouds/access/react`  — AccessProvider + hooks.
+ *
+ * This package carries NO policy logic. Every access decision belongs to the
+ * Control Plane (control-plane-doctrine §5); the SDK only asks the five
+ * operating questions and enforces the answers, fail-closed.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/react/hooks.d.ts

@@ -0,0 +1,30 @@
+import type { AccessDecision, Grant, OperatorIdentity, PermissionResolver, ProjectScope } from '../types.js';
+/** Who is the current operator? (null when unauthenticated). */
+export declare function useOperator(): OperatorIdentity | null;
+/** What project scope is being acted in? */
+export declare function useProjectScope(): ProjectScope;
+/** What capabilities does this operator hold here? (the granted `<primitive>.<verb>` set). */
+export declare function useGrants(): Grant[];
+/**
+ * "What capabilities are granted?" — the doctrine's fifth operating question.
+ * Same granted set as {@link useGrants}, named for the question it answers.
+ */
+export declare function useCapabilities(): Grant[];
+/**
+ * Can this action be performed? Reflects the fetched grants snapshot, fail-closed:
+ * `allowed` when the capability is in the granted set; `unknown` when there is no
+ * operator (nothing resolved yet); `denied` otherwise. The load-bearing check is
+ * still the server-side `access.can` before a read/turn is forwarded — this hook
+ * is for UX gating, never the enforcement.
+ */
+export declare function useCan(action: Grant): AccessDecision;
+/**
+ * The bridge: a PermissionResolver built over the CURRENT grants snapshot —
+ * the same shape `createOperatorPermissionResolver(authenticated, grants)`
+ * produces (a Set-membership check; `unknown` ⇒ denied). Because the provider
+ * refetches the snapshot on mount / focus / route-change / TTL, the grant SOURCE
+ * is live without the resolver SHAPE changing. Memoized on the snapshot so the
+ * shell's sync decisions stay stable between refetches.
+ */
+export declare function useOperatorPermissionResolver(): PermissionResolver;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/react/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG7G,gEAAgE;AAChE,wBAAgB,WAAW,IAAI,gBAAgB,GAAG,IAAI,CAErD;AAED,4CAA4C;AAC5C,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAEnC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,KAAK,EAAE,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,KAAK,GAAG,cAAc,CAMpD;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,IAAI,kBAAkB,CAMlE"}

package/dist/react/hooks.js

@@ -0,0 +1,59 @@
+'use client';
+/**
+ * The Access hooks — the five operating questions, answered over the current
+ * fresh session snapshot the AccessProvider holds. Every hook is fail-closed:
+ * a capability not in the granted snapshot resolves `unknown` (⇒ denied by the
+ * shell). There is NO policy here — the grants were decided by the Control Plane.
+ */
+import * as React from 'react';
+import { useAccessContext } from './provider.js';
+/** Who is the current operator? (null when unauthenticated). */
+export function useOperator() {
+    return useAccessContext().session.identity;
+}
+/** What project scope is being acted in? */
+export function useProjectScope() {
+    return useAccessContext().session.scope;
+}
+/** What capabilities does this operator hold here? (the granted `<primitive>.<verb>` set). */
+export function useGrants() {
+    return useAccessContext().session.grants;
+}
+/**
+ * "What capabilities are granted?" — the doctrine's fifth operating question.
+ * Same granted set as {@link useGrants}, named for the question it answers.
+ */
+export function useCapabilities() {
+    return useAccessContext().session.grants;
+}
+/**
+ * Can this action be performed? Reflects the fetched grants snapshot, fail-closed:
+ * `allowed` when the capability is in the granted set; `unknown` when there is no
+ * operator (nothing resolved yet); `denied` otherwise. The load-bearing check is
+ * still the server-side `access.can` before a read/turn is forwarded — this hook
+ * is for UX gating, never the enforcement.
+ */
+export function useCan(action) {
+    const { session, authenticated } = useAccessContext();
+    return React.useMemo(() => {
+        if (!authenticated)
+            return 'unknown';
+        return session.grants.includes(action) ? 'allowed' : 'denied';
+    }, [authenticated, session.grants, action]);
+}
+/**
+ * The bridge: a PermissionResolver built over the CURRENT grants snapshot —
+ * the same shape `createOperatorPermissionResolver(authenticated, grants)`
+ * produces (a Set-membership check; `unknown` ⇒ denied). Because the provider
+ * refetches the snapshot on mount / focus / route-change / TTL, the grant SOURCE
+ * is live without the resolver SHAPE changing. Memoized on the snapshot so the
+ * shell's sync decisions stay stable between refetches.
+ */
+export function useOperatorPermissionResolver() {
+    const { session, authenticated } = useAccessContext();
+    return React.useMemo(() => {
+        const granted = new Set(authenticated ? session.grants : []);
+        return (permission) => (granted.has(permission) ? 'allowed' : 'unknown');
+    }, [authenticated, session.grants]);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/react/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/react/hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,gEAAgE;AAChE,MAAM,UAAU,WAAW;IACzB,OAAO,gBAAgB,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;AAC7C,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,eAAe;IAC7B,OAAO,gBAAgB,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;AAC1C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,SAAS;IACvB,OAAO,gBAAgB,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,gBAAgB,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,MAAa;IAClC,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,EAAE,CAAC;IACtD,OAAO,KAAK,CAAC,OAAO,CAAiB,GAAG,EAAE;QACxC,IAAI,CAAC,aAAa;YAAE,OAAO,SAAS,CAAC;QACrC,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IAChE,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,6BAA6B;IAC3C,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,gBAAgB,EAAE,CAAC;IACtD,OAAO,KAAK,CAAC,OAAO,CAAqB,GAAG,EAAE;QAC5C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrE,OAAO,CAAC,UAAkB,EAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnG,CAAC,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@consciousclouds/access/react` — AccessProvider + the operator hooks.
+ * Client-only. Reads a fresh Access session snapshot from the product's
+ * same-origin BFF seam; carries no policy and no long-lived cache.
+ */
+export { AccessProvider, useAccessContext } from './provider.js';
+export type { AccessProviderProps, AccessContextValue } from './provider.js';
+export { useOperator, useProjectScope, useGrants, useCapabilities, useCan, useOperatorPermissionResolver, } from './hooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE7E,OAAO,EACL,WAAW,EACX,eAAe,EACf,SAAS,EACT,eAAe,EACf,MAAM,EACN,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,9 @@
+'use client';
+/**
+ * `@consciousclouds/access/react` — AccessProvider + the operator hooks.
+ * Client-only. Reads a fresh Access session snapshot from the product's
+ * same-origin BFF seam; carries no policy and no long-lived cache.
+ */
+export { AccessProvider, useAccessContext } from './provider.js';
+export { useOperator, useProjectScope, useGrants, useCapabilities, useCan, useOperatorPermissionResolver, } from './hooks.js';
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjE,OAAO,EACL,WAAW,EACX,eAAe,EACf,SAAS,EACT,eAAe,EACf,MAAM,EACN,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}

package/dist/react/provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AccessProvider — the client-side context that holds a FRESH Access session
+ * snapshot for the current operator + scope. It fetches the snapshot from the
+ * product's SAME-ORIGIN BFF seam (default `/api/access/session`), never the
+ * Control Plane directly — the browser holds no operator token and the Control
+ * Plane URL is server-only.
+ *
+ * NO long-lived cache (control-plane-doctrine §4): the snapshot is refetched on
+ * mount, on window focus / tab visibility, on a short TTL, and whenever the
+ * caller-supplied `routeKey` changes (pass `usePathname()` for route-change
+ * revalidation without coupling this SDK to any router). Fail-closed: a failed
+ * fetch yields an empty session (no identity, no grants).
+ */
+import * as React from 'react';
+import type { AccessSession, ProjectScope } from '../types.js';
+export interface AccessContextValue {
+    /** The current fresh session snapshot. */
+    session: AccessSession;
+    /** True when an operator identity is present in the snapshot. */
+    authenticated: boolean;
+    /** Force a refetch of the session snapshot. */
+    refresh(): Promise<void>;
+}
+export interface AccessProviderProps {
+    /** The project scope this surface acts in (also the fallback when a snapshot has none). */
+    scope: ProjectScope;
+    /** An SSR-resolved snapshot to paint from before the first client fetch. */
+    initialSession?: AccessSession;
+    /** The same-origin BFF route returning an AccessSession JSON. */
+    sessionEndpoint?: string;
+    /** Freshness window (seconds) before a background revalidation. */
+    ttlSeconds?: number;
+    /** A value that changes on navigation (e.g. `usePathname()`) → triggers a refetch. */
+    routeKey?: string;
+    children: React.ReactNode;
+}
+export declare function AccessProvider({ scope, initialSession, sessionEndpoint, ttlSeconds, routeKey, children, }: AccessProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Internal: read the Access context (throws when used outside an AccessProvider). */
+export declare function useAccessContext(): AccessContextValue;
+//# sourceMappingURL=provider.d.ts.map

package/dist/react/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/react/provider.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;IACvB,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,+CAA+C;IAC/C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAID,MAAM,WAAW,mBAAmB;IAClC,2FAA2F;IAC3F,KAAK,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAiBD,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,cAAc,EACd,eAAuC,EACvC,UAAe,EACf,QAAQ,EACR,QAAQ,GACT,EAAE,mBAAmB,2CAqDrB;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,IAAI,kBAAkB,CAIrD"}

package/dist/react/provider.js

@@ -0,0 +1,84 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AccessProvider — the client-side context that holds a FRESH Access session
+ * snapshot for the current operator + scope. It fetches the snapshot from the
+ * product's SAME-ORIGIN BFF seam (default `/api/access/session`), never the
+ * Control Plane directly — the browser holds no operator token and the Control
+ * Plane URL is server-only.
+ *
+ * NO long-lived cache (control-plane-doctrine §4): the snapshot is refetched on
+ * mount, on window focus / tab visibility, on a short TTL, and whenever the
+ * caller-supplied `routeKey` changes (pass `usePathname()` for route-change
+ * revalidation without coupling this SDK to any router). Fail-closed: a failed
+ * fetch yields an empty session (no identity, no grants).
+ */
+import * as React from 'react';
+const AccessContext = React.createContext(null);
+function emptySession(scope, ttlSeconds) {
+    return { identity: null, scope, roles: [], grants: [], ttlSeconds };
+}
+function normalize(raw, scope, ttlSeconds) {
+    const s = (raw ?? {});
+    return {
+        identity: s.identity ?? null,
+        scope: s.scope ?? scope,
+        roles: Array.isArray(s.roles) ? s.roles : [],
+        grants: Array.isArray(s.grants) ? s.grants : [],
+        ttlSeconds: typeof s.ttlSeconds === 'number' ? s.ttlSeconds : ttlSeconds,
+    };
+}
+export function AccessProvider({ scope, initialSession, sessionEndpoint = '/api/access/session', ttlSeconds = 30, routeKey, children, }) {
+    const [session, setSession] = React.useState(() => initialSession ?? emptySession(scope, ttlSeconds));
+    const refresh = React.useCallback(async () => {
+        try {
+            const res = await fetch(sessionEndpoint, { cache: 'no-store', credentials: 'same-origin' });
+            if (!res.ok) {
+                setSession(emptySession(scope, ttlSeconds));
+                return;
+            }
+            const body = (await res.json());
+            setSession(normalize(body, scope, ttlSeconds));
+        }
+        catch {
+            // Fail-closed: an unreachable BFF yields no grants.
+            setSession(emptySession(scope, ttlSeconds));
+        }
+    }, [sessionEndpoint, scope, ttlSeconds]);
+    // Refetch on mount and whenever the route changes.
+    React.useEffect(() => {
+        void refresh();
+    }, [refresh, routeKey]);
+    // Refetch on window focus / tab becoming visible.
+    React.useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const onFocus = () => void refresh();
+        const onVisible = () => {
+            if (document.visibilityState === 'visible')
+                void refresh();
+        };
+        window.addEventListener('focus', onFocus);
+        document.addEventListener('visibilitychange', onVisible);
+        return () => {
+            window.removeEventListener('focus', onFocus);
+            document.removeEventListener('visibilitychange', onVisible);
+        };
+    }, [refresh]);
+    // Short-TTL background revalidation (no long-lived cache).
+    React.useEffect(() => {
+        const ttl = session.ttlSeconds > 0 ? session.ttlSeconds : ttlSeconds;
+        const id = setInterval(() => void refresh(), Math.max(5, ttl) * 1000);
+        return () => clearInterval(id);
+    }, [refresh, session.ttlSeconds, ttlSeconds]);
+    const value = React.useMemo(() => ({ session, authenticated: !!session.identity, refresh }), [session, refresh]);
+    return _jsx(AccessContext.Provider, { value: value, children: children });
+}
+/** Internal: read the Access context (throws when used outside an AccessProvider). */
+export function useAccessContext() {
+    const ctx = React.useContext(AccessContext);
+    if (!ctx)
+        throw new Error('useAccess* must be used within an <AccessProvider>');
+    return ctx;
+}
+//# sourceMappingURL=provider.js.map

package/dist/react/provider.js.map

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

package/dist/server/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `@consciousclouds/access/server` — the request-bound BFF adapter. It reads the
+ * operator token from the request's httpOnly cookie (name configurable) and
+ * calls the Control Plane server-side, so the Control Plane URL and the operator
+ * token never reach the browser.
+ *
+ * FAIL-CLOSED by construction — this is the load-bearing enforcement seam
+ * (control-plane-doctrine §4): any deny, unreachable Control Plane, or thrown
+ * error resolves to `denied` / an empty session. A failure can never widen
+ * access. Carries NO policy: it forwards the operator's identity to the Control
+ * Plane, which decides.
+ */
+import type { AccessDecision, AccessIntent, AccessSession, Grant, OperatorIdentity, ProjectScope } from '../types.js';
+/** The minimum request shape the adapter needs — satisfied by a Fetch `Request`
+ * or `{ headers: <Next headers()> }`. */
+export interface RequestLike {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/** Configuration for the request-bound adapter. */
+export interface ServerAccessConfig {
+    /** Control Plane base URL — SERVER-ONLY (never `NEXT_PUBLIC_`). */
+    baseUrl: string;
+    /** The httpOnly cookie carrying the operator token (e.g. `ccu_operator`). */
+    cookieName: string;
+    /** The default project scope for this surface (single-project surfaces set it once). */
+    scope?: ProjectScope;
+    /** The capability candidates whose granted subset seeds `AccessSession.grants`
+     * (the set this surface gates its nav on). Probed via the Control Plane — no policy here. */
+    capabilities?: readonly Grant[];
+    /** Optional fetch implementation. */
+    fetchImpl?: typeof fetch;
+    /** Freshness window the assembled AccessSession advertises. */
+    ttlSeconds?: number;
+}
+/** The request-bound adapter surface. */
+export interface ServerAccess {
+    /** Who is the current operator? (decoded from the cookie for display; null when absent). */
+    identity(req: RequestLike): OperatorIdentity | null;
+    /** What project scope is this surface acting in? */
+    scope(req?: RequestLike): ProjectScope;
+    /** What permissions does the operator have here? (fail-closed empty session on any failure). */
+    session(req: RequestLike, scope?: ProjectScope): Promise<AccessSession>;
+    /** Can this action be performed? (uncached, fail-closed — deny/unreachable/throw ⇒ denied). */
+    can(req: RequestLike, scope: ProjectScope, action: Grant, intent?: AccessIntent): Promise<AccessDecision>;
+}
+/** Create the request-bound BFF adapter. */
+export declare function createAccess(config: ServerAccessConfig): ServerAccess;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,aAAa,EACb,KAAK,EACL,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB;yCACyC;AACzC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;iGAC6F;IAC7F,YAAY,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IAChC,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,yCAAyC;AACzC,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC;IACpD,oDAAoD;IACpD,KAAK,CAAC,GAAG,CAAC,EAAE,WAAW,GAAG,YAAY,CAAC;IACvC,gGAAgG;IAChG,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACxE,+FAA+F;IAC/F,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3G;AAeD,4CAA4C;AAC5C,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAwDrE"}

package/dist/server/index.js

@@ -0,0 +1,77 @@
+/**
+ * `@consciousclouds/access/server` — the request-bound BFF adapter. It reads the
+ * operator token from the request's httpOnly cookie (name configurable) and
+ * calls the Control Plane server-side, so the Control Plane URL and the operator
+ * token never reach the browser.
+ *
+ * FAIL-CLOSED by construction — this is the load-bearing enforcement seam
+ * (control-plane-doctrine §4): any deny, unreachable Control Plane, or thrown
+ * error resolves to `denied` / an empty session. A failure can never widen
+ * access. Carries NO policy: it forwards the operator's identity to the Control
+ * Plane, which decides.
+ */
+import { createAccessClient, identityFromToken } from '../client/index.js';
+const EMPTY_SCOPE = { project: '', environment: '' };
+/** Pull one cookie value out of a raw `Cookie:` header. */
+function readCookie(header, name) {
+    if (!header)
+        return null;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return decodeURIComponent(part.slice(eq + 1).trim());
+    }
+    return null;
+}
+/** Create the request-bound BFF adapter. */
+export function createAccess(config) {
+    const clientConfig = {
+        baseUrl: config.baseUrl,
+        fetchImpl: config.fetchImpl,
+        ttlSeconds: config.ttlSeconds,
+    };
+    const client = createAccessClient(clientConfig);
+    const candidates = config.capabilities ?? [];
+    const tokenOf = (req) => readCookie(req.headers.get('cookie'), config.cookieName);
+    const scopeOf = (explicit) => explicit ?? config.scope ?? EMPTY_SCOPE;
+    function identity(req) {
+        return identityFromToken(tokenOf(req));
+    }
+    function scope(_req) {
+        return scopeOf();
+    }
+    async function session(req, explicit) {
+        const scoped = scopeOf(explicit);
+        const token = tokenOf(req);
+        if (!token)
+            return { identity: null, scope: scoped, roles: [], grants: [], ttlSeconds: config.ttlSeconds ?? 30 };
+        try {
+            return await client.session(token, scoped, candidates);
+        }
+        catch {
+            // Fail-closed: an unreachable/erroring Control Plane yields no grants.
+            return {
+                identity: identityFromToken(token),
+                scope: scoped,
+                roles: [],
+                grants: [],
+                ttlSeconds: config.ttlSeconds ?? 30,
+            };
+        }
+    }
+    async function can(req, explicit, action, intent = 'mutate') {
+        const token = tokenOf(req);
+        if (!token)
+            return 'denied';
+        try {
+            return await client.can(token, scopeOf(explicit), action, intent);
+        }
+        catch {
+            return 'denied';
+        }
+    }
+    return { identity, scope, session, can };
+}
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The Access vocabulary — TYPES ONLY. No React, no `fetch`, no policy. This is
+ * the root export (`@consciousclouds/access`); everything here is inert data
+ * shapes that both the browser and the server share.
+ *
+ * The five operating questions the Control Plane answers (control-plane-doctrine
+ * §5) map onto these types:
+ *   - Who is the current operator?           → OperatorIdentity
+ *   - What project is being entered?         → ProjectScope
+ *   - What permissions does the operator have here? → AccessSession.roles / .grants
+ *   - Can this action be performed?          → AccessDecision (from `can`)
+ *   - What capabilities are granted?         → AccessSession.grants (Grant[])
+ */
+import type { Capability } from '@consciousclouds/capability-sdk';
+/**
+ * The authenticated operator, decoded from the operator JWT for DISPLAY (never
+ * verified here — the gateway does the real signature/iss/aud verification).
+ * `iss`/`aud` are the operator plane's fixed identity (`ccu-admin.identity` /
+ * `ccu-admin.app`); `exp` is seconds since epoch when present.
+ */
+export interface OperatorIdentity {
+    sub: string;
+    email: string;
+    displayName?: string;
+    iss: string;
+    aud: string;
+    exp?: number;
+}
+/**
+ * The project + environment an operator is acting in. The Control Plane keys
+ * Access decisions on the project slug; the environment travels with it (env =
+ * a Neon branch, per the parity toolchain).
+ */
+export interface ProjectScope {
+    project: string;
+    environment: string;
+}
+/**
+ * A single granted capability — REUSES the platform `Capability` vocabulary
+ * (`<primitive>.<verb>`, e.g. `factory.observe`, `assistant.turn`). There is
+ * exactly ONE permission vocabulary; this SDK invents no second one.
+ */
+export type Grant = Capability;
+/**
+ * The three outcomes a permission check can produce. This union is IDENTICAL to
+ * `@consciousclouds/operator-shell`'s `PermissionDecision` (allowed | denied |
+ * unknown) — a resolver returning `AccessDecision` is assignable wherever the
+ * shell wants a `PermissionResolver`. `unknown` ⇒ denied (fail-closed): a value
+ * the resolver could not resolve to `allowed` never widens access.
+ */
+export type AccessDecision = 'allowed' | 'denied' | 'unknown';
+/**
+ * The intent of an authorization check. It gates exactly one boundary in the
+ * Control Plane — the read-only cross-grant gate (a `read_only` assignment
+ * attempting a `mutate` is denied). Admin reads are `read`; a turn is `mutate`.
+ */
+export type AccessIntent = 'read' | 'mutate';
+/**
+ * The operator's answer to "what permissions do I have here?" for one project
+ * scope, as the SDK assembles it from the Control Plane:
+ *   - `roles`  — the role keys the operator holds at this scope (from
+ *                `GET /access/session`, whose grants are ROLE assignments).
+ *   - `grants` — the resolved `<primitive>.<verb>` capabilities the operator is
+ *                actually allowed here. The Control Plane's `/access/session`
+ *                returns roles, not resolved capabilities, so the granted subset
+ *                is resolved by asking the Control Plane's authorize decision for
+ *                a candidate capability set (policy-free aggregation — the
+ *                Control Plane decides each one).
+ *   - `ttlSeconds` — how long a consumer may treat this snapshot as fresh before
+ *                revalidating. Short by design; the SDK holds no long-lived cache.
+ * Fail-closed: an invalid/expired/logged-out session yields empty `roles` +
+ * `grants` (nothing to gate `allowed`).
+ */
+export interface AccessSession {
+    identity: OperatorIdentity | null;
+    scope: ProjectScope;
+    roles: string[];
+    grants: Grant[];
+    ttlSeconds: number;
+}
+/**
+ * A resolver from a permission REFERENCE → a decision (sync or async),
+ * structurally identical to `@consciousclouds/operator-shell`'s
+ * `PermissionResolver`. Declared here so the SDK need not depend on the shell.
+ */
+export type PermissionResolver = (permission: string) => AccessDecision | Promise<AccessDecision>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,UAAU,EAAE,MAAM,KACf,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * The Access vocabulary — TYPES ONLY. No React, no `fetch`, no policy. This is
+ * the root export (`@consciousclouds/access`); everything here is inert data
+ * shapes that both the browser and the server share.
+ *
+ * The five operating questions the Control Plane answers (control-plane-doctrine
+ * §5) map onto these types:
+ *   - Who is the current operator?           → OperatorIdentity
+ *   - What project is being entered?         → ProjectScope
+ *   - What permissions does the operator have here? → AccessSession.roles / .grants
+ *   - Can this action be performed?          → AccessDecision (from `can`)
+ *   - What capabilities are granted?         → AccessSession.grants (Grant[])
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@consciousclouds/access",
+  "version": "0.1.0",
+  "description": "Conscious Clouds Access SDK — the thin, policy-free client for the Control Plane's operator identity + Access surface. Types (root) + isomorphic HTTP wrappers (/client) + a request-bound fail-closed BFF adapter (/server) + React hooks & AccessProvider (/react). Reuses the `Capability` `<primitive>.<verb>` vocabulary and the operator-shell's allowed|denied|unknown decision union. NO policy logic — every decision is the Control Plane's; the SDK only asks the five operating questions and enforces the answers (fail-closed).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run clean && bun run build && bun run type-check"
+  },
+  "dependencies": {
+    "@consciousclouds/capability-sdk": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@types/react": "^19.2.7",
+    "react": "^19.2.3",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}