@gnldev/auth 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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, whether in Source or
+      Object form, 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 any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to 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 otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated 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 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 a Contribution incorporated 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, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          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 as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this 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.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   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 warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, 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 consequential 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 any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional 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 act 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.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Karaca Yılmaz (https://gnl.dev)
+
+   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,138 @@
+# @gnldev/auth
+
+The auth contract the rest of the framework speaks, plus a role-based default you can use as-is.
+
+Auth is **opt-in**: leave it out and the REST API and Studio stay open (fine for local work). Wire a
+provider in and every route is gated. In production, a missing provider is an error rather than a
+silent open door.
+
+## Install
+
+> Install: `pnpm add @gnldev/auth` — or use it from a [repo clone](https://github.com/Karaca7/gnldev): `pnpm install && pnpm -r build`.
+
+```bash
+npm i @gnldev/auth
+```
+
+## Four credential classes
+
+Pick the class by **who holds the token**, not by how much it needs to do. Credentials can be a bearer
+token or a user/password pair for basic auth — comparison is constant-time.
+
+| Class | Who holds it | Organization | Can |
+|---|---|---|---|
+| `superAdmin` | you, running the platform | none, by design | everything, across every organization |
+| `admin` | a customer's operator | bound | manage that organization: Studio, budgets, users, workflows |
+| `client` | a customer's **backend server** | bound | run agents, cancel runs, read — nothing else |
+| `viewer` | a read-only operator | bound | read |
+
+```ts
+import { roleAuth } from '@gnldev/auth';
+import { createRestApi } from '@gnldev/server';
+
+const auth = roleAuth({
+  // The credential your APPLICATION carries. It serves many end users under one token, so every
+  // request names the end user it acts for (see below).
+  client: { token: process.env.GNL_CLIENT_TOKEN, orgId: 'acme' },
+  // The credential a PERSON carries, for Studio.
+  admin: { token: process.env.GNL_ADMIN_TOKEN, orgId: 'acme' },
+});
+
+const app = createRestApi(config, { auth });
+```
+
+`roleAuth` returns `undefined` when no class is configured — that is what keeps auth opt-in.
+
+### Give your application `client`, not `admin`
+
+`admin` is an operator credential: it cancels runs, edits budgets, manages users and reads the whole
+organization's history. An application that only needs to run an agent has no business holding that,
+and if it leaks, none of those are things you wanted a leaked key to reach.
+
+`client` is a **whitelist** — `agents:run`, `workflow:run`, `run:cancel`, plus reads. Anything else is
+refused, including routes added in later versions. That is the direction you want the default to fail.
+
+### A `client` names the end user it acts for
+
+One application credential serves many end users, so the request says which one:
+
+```ts
+const GNL = process.env.GNL_URL!;
+const CLIENT_TOKEN = process.env.GNL_CLIENT_TOKEN!;
+
+await fetch(`${GNL}/agents/support/run`, {
+  method: 'POST',
+  headers: { authorization: `Bearer ${CLIENT_TOKEN}`, 'content-type': 'application/json' },
+  body: JSON.stringify({
+    runId: 'r-882',
+    prompt: 'where is my order',
+    threadId: 't-ayse-1',
+    resourceId: 'u-ayse',   // ← WHOSE request this is
+  }),
+});
+```
+
+`resourceId` is what separates one end user's conversation, memory and runs from another's. A `client`
+request that omits it is refused (`400`) rather than served unscoped — without a subject there is
+nothing to keep two of your users apart. Operator classes may omit it: they work across the
+organization by design.
+
+You can then ask for one user's data, and have ownership checked:
+
+```
+GET /runs?resourceId=u-ayse             → only that user's runs
+GET /threads?resourceId=u-ayse          → only that user's conversations
+GET /runs/r-882?resourceId=u-mehmet     → 403, the run belongs to someone else
+```
+
+> **Keep the client token on your server.** It is trusted to say who it acts for, so anyone holding it
+> can claim any `resourceId`. That is safe in your backend, where you already know who your user is.
+> It is not safe in a browser or a mobile app — ship neither the token nor a proxy that forwards a
+> caller-supplied `resourceId` unchecked.
+
+### `superAdmin` is stated, never inferred
+
+An identity belonging to no organization is **not** treated as an operator by accident. Once `org` is
+configured, an unbound identity is refused unless it is declared `superAdmin`; otherwise a forgotten
+`orgId` would quietly mint a cross-organization super-admin.
+
+## The contract
+
+| Export | What it is |
+|---|---|
+| `AuthProvider` | `authenticate(request)` → a `Principal` or `null`, then `authorize(principal, request, ctx)` → `{ allow }` |
+| `roleAuth` | The bundled provider above |
+| `CLIENT_WRITES` | The exact set of writes a `client` may perform — read it rather than guessing |
+| `PLATFORM_ADMIN_ROLE` / `isPlatformAdmin` | The reserved cross-organization grant `superAdmin` carries |
+| `makeGate` | Turns a provider into a gate a host can apply to routes |
+| `principalOf` | Reads the principal a gate resolved for a request |
+| `normalizeAuth` / `fromReadWrite` | Accepts the older `{ read, write }` predicate pair and adapts it to the provider interface |
+
+## Extending it
+
+`AuthProvider` is the seam. Anything implementing it works: your own JWT logic, an identity service,
+or the paid `@gnldev/auth-ee`, which plugs into this same interface to add SSO, RBAC, fine-grained
+authorization and a relational user store. Nothing in this package needs to change to swap providers.
+
+A provider may also declare `capabilities()` — that is how a host learns whether features like
+role-based access or multi-organization scoping are available.
+
+### What the paid provider adds on top of these four
+
+The four classes above are **fixed**: `viewer` reads everything inside its organization, and there is
+no way to narrow it. `@gnldev/auth-ee` replaces the classes with per-user permissions, so you choose
+what each person sees:
+
+```
+Ayşe   runs:read ✓   threads:read ✗   money:read ✗    → sees that a run failed,
+                                                         not what the customer typed into it
+```
+
+Reads are named the same way writes are — `runs`, `threads`, `money`, `audit`, `users`, `catalog` —
+and `*:read` still means all of them, so nothing an existing grant could reach becomes unreachable.
+Isolation itself is **not** the paid part: the organization boundary, the `client` whitelist and the
+`resourceId` rules above are all in this package, and none of them turn on when you pay.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/adapter.d.ts

@@ -0,0 +1,38 @@
+import type { AuthProvider } from './types.js';
+/** Old role-based hook: read = GET (viewer), write = POST/PUT/PATCH/DELETE (admin). */
+export interface ReadWriteAuth {
+    read?: (req: Request) => boolean | Promise<boolean>;
+    write?: (req: Request) => boolean | Promise<boolean>;
+}
+/**
+ * Can this provider ever produce a principal?
+ *
+ * `authenticate() === null` is ambiguous: it means EITHER "this request carried no token" (a
+ * roleAuth caller who should get 401) OR "this provider has no principal model at all and never
+ * will" (the {read,write} pair below). A host that scopes organizations by identity has to tell
+ * those apart — the first is a per-request condition, the second is a configuration that cannot
+ * isolate anything, because there is no identity to bind an org to. Collapsing them makes the
+ * unauthenticated caller's 401 turn into a misleading 403, or leaves the unsafe configuration open.
+ *
+ * Absent on hand-written providers, so `!== false` is the compatible reading: unknown means capable.
+ */
+export declare function bindsIdentity(auth: AuthProvider | undefined): boolean;
+/** {read,write} → AuthProvider. If there's no fn in that direction, it's unrestricted (preserves the existing `!fn || fn(c)` behavior). */
+export declare function fromReadWrite(rw: ReadWriteAuth): AuthProvider;
+/**
+ * AuthProvider | {read,write} | undefined → AuthProvider | undefined (hosts reduce to a single type).
+ *
+ * Throws on an object that is neither, because the alternative is the worst possible answer. The
+ * previous reading was "not a provider ⇒ it must be {read,write}", and `fromReadWrite` treats a
+ * missing direction as unrestricted — so ANY unrecognised object became a provider that allows
+ * everything. The realistic way to hit that is the credential map the scaffold writes:
+ *
+ *   createRestApi({ auth: { admin: { token: 's3cret' } } })   // looks protected, allows everyone
+ *
+ * That exact shape shipped once already: @gnldev/studio grew `resolveConfigAuth` for it, but
+ * @gnldev/server still calls this directly, so the hole stayed open on the other host. Refusing here
+ * closes it for every caller and turns a silent, invisible failure into an error at startup — the one
+ * moment it can still be fixed. A caller that really wants no restrictions passes `undefined`; that
+ * intent is expressible and needs no guessing.
+ */
+export declare function normalizeAuth(auth?: AuthProvider | ReadWriteAuth): AuthProvider | undefined;

package/dist/adapter.js

@@ -0,0 +1,79 @@
+/**
+ * Can this provider ever produce a principal?
+ *
+ * `authenticate() === null` is ambiguous: it means EITHER "this request carried no token" (a
+ * roleAuth caller who should get 401) OR "this provider has no principal model at all and never
+ * will" (the {read,write} pair below). A host that scopes organizations by identity has to tell
+ * those apart — the first is a per-request condition, the second is a configuration that cannot
+ * isolate anything, because there is no identity to bind an org to. Collapsing them makes the
+ * unauthenticated caller's 401 turn into a misleading 403, or leaves the unsafe configuration open.
+ *
+ * Absent on hand-written providers, so `!== false` is the compatible reading: unknown means capable.
+ */
+export function bindsIdentity(auth) {
+    return !!auth && auth.bindsIdentity !== false;
+}
+/** {read,write} → AuthProvider. If there's no fn in that direction, it's unrestricted (preserves the existing `!fn || fn(c)` behavior). */
+export function fromReadWrite(rw) {
+    return {
+        bindsIdentity: false,
+        authenticate() {
+            return null; // no principal model; the decision is made in the predicate.
+        },
+        async authorize(_p, req, ctx) {
+            const fn = ctx.action === 'read' ? rw.read : rw.write;
+            if (!fn)
+                return { allow: true };
+            const ok = await fn(req);
+            return ok ? { allow: true } : { allow: false, status: ctx.action === 'write' ? 403 : 401 };
+        },
+    };
+}
+function isProvider(x) {
+    return typeof x.authorize === 'function';
+}
+/**
+ * AuthProvider | {read,write} | undefined → AuthProvider | undefined (hosts reduce to a single type).
+ *
+ * Throws on an object that is neither, because the alternative is the worst possible answer. The
+ * previous reading was "not a provider ⇒ it must be {read,write}", and `fromReadWrite` treats a
+ * missing direction as unrestricted — so ANY unrecognised object became a provider that allows
+ * everything. The realistic way to hit that is the credential map the scaffold writes:
+ *
+ *   createRestApi({ auth: { admin: { token: 's3cret' } } })   // looks protected, allows everyone
+ *
+ * That exact shape shipped once already: @gnldev/studio grew `resolveConfigAuth` for it, but
+ * @gnldev/server still calls this directly, so the hole stayed open on the other host. Refusing here
+ * closes it for every caller and turns a silent, invisible failure into an error at startup — the one
+ * moment it can still be fixed. A caller that really wants no restrictions passes `undefined`; that
+ * intent is expressible and needs no guessing.
+ */
+export function normalizeAuth(auth) {
+    if (!auth)
+        return undefined;
+    if (isProvider(auth))
+        return auth;
+    const rw = auth;
+    // Each side that is PRESENT must be a function. The check used to be `read is fn OR write is fn`,
+    // which short-circuits: `{ read: fn, write: { admin: { token } } }` — one direction a predicate, the
+    // other a credential map, which is what a half-finished config looks like — passed here and then
+    // threw at REQUEST time, on the first write, in production. That is the silent invisible failure
+    // this whole function exists to move to startup.
+    const sides = ['read', 'write'].filter((k) => rw[k] !== undefined);
+    if (sides.length > 0) {
+        const bad = sides.filter((k) => typeof rw[k] !== 'function');
+        if (bad.length === 0)
+            return fromReadWrite(rw);
+        throw new TypeError(`@gnldev/auth: \`auth.${bad.join('\` and \`auth.')}\` must be a function ` +
+            `(got ${bad.map((k) => `${k}: ${typeof rw[k]}`).join(', ')}). ` +
+            `A {read, write} pair takes predicates; a credential map like { admin: { token } } has to be ` +
+            `wrapped: \`roleAuth({ admin: { token } })\`. Left as it is, this authorises nothing until the ` +
+            `first request and then throws there instead.`);
+    }
+    const keys = Object.keys(auth).slice(0, 5).join(', ') || '(no keys)';
+    throw new TypeError(`@gnldev/auth: \`auth\` is neither an AuthProvider (no \`authorize\` function) nor a {read, write} ` +
+        `pair (no \`read\`/\`write\` function). Got an object with: ${keys}. ` +
+        `If this is a credential map like { admin: { token } }, wrap it: \`roleAuth({ admin: { token } })\`. ` +
+        `Passing it directly would authorise every request. For no restrictions, omit \`auth\` entirely.`);
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAA8B;IAC1D,OAAO,CAAC,CAAC,IAAI,IAAK,IAAoC,CAAC,aAAa,KAAK,KAAK,CAAC;AACjF,CAAC;AAED,2IAA2I;AAC3I,MAAM,UAAU,aAAa,CAAC,EAAiB;IAC7C,OAAO;QACL,aAAa,EAAE,KAAK;QACpB,YAAY;YACV,OAAO,IAAI,CAAC,CAAC,6DAA6D;QAC5E,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,EAAE,EAAE,GAAY,EAAE,GAAgB;YAChD,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC;YACtD,IAAI,CAAC,EAAE;gBAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YAChC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QAC7F,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,CAA+B;IACjD,OAAO,OAAQ,CAAkB,CAAC,SAAS,KAAK,UAAU,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,IAAmC;IAC/D,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,EAAE,GAAG,IAAqB,CAAC;IACjC,kGAAkG;IAClG,qGAAqG;IACrG,iGAAiG;IACjG,iGAAiG;IACjG,iDAAiD;IACjD,MAAM,KAAK,GAAI,CAAC,MAAM,EAAE,OAAO,CAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC;QAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,IAAI,SAAS,CACjB,wBAAwB,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,wBAAwB;YAC1E,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAC/D,8FAA8F;YAC9F,gGAAgG;YAChG,8CAA8C,CAC/C,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAc,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC;IAC/E,MAAM,IAAI,SAAS,CACjB,oGAAoG;QACpG,8DAA8D,IAAI,IAAI;QACtE,sGAAsG;QACtG,iGAAiG,CAClG,CAAC;AACJ,CAAC","sourcesContent":["// Backward compatibility: wraps the old {read,write} predicate pair (StudioAuth / examples/app) into an AuthProvider.\nimport type { AuthProvider, Decision, AuthContext } from './types.js';\n\n/** Old role-based hook: read = GET (viewer), write = POST/PUT/PATCH/DELETE (admin). */\nexport interface ReadWriteAuth {\n  read?: (req: Request) => boolean | Promise<boolean>;\n  write?: (req: Request) => boolean | Promise<boolean>;\n}\n\n/**\n * Can this provider ever produce a principal?\n *\n * `authenticate() === null` is ambiguous: it means EITHER \"this request carried no token\" (a\n * roleAuth caller who should get 401) OR \"this provider has no principal model at all and never\n * will\" (the {read,write} pair below). A host that scopes organizations by identity has to tell\n * those apart — the first is a per-request condition, the second is a configuration that cannot\n * isolate anything, because there is no identity to bind an org to. Collapsing them makes the\n * unauthenticated caller's 401 turn into a misleading 403, or leaves the unsafe configuration open.\n *\n * Absent on hand-written providers, so `!== false` is the compatible reading: unknown means capable.\n */\nexport function bindsIdentity(auth: AuthProvider | undefined): boolean {\n  return !!auth && (auth as { bindsIdentity?: boolean }).bindsIdentity !== false;\n}\n\n/** {read,write} → AuthProvider. If there's no fn in that direction, it's unrestricted (preserves the existing `!fn || fn(c)` behavior). */\nexport function fromReadWrite(rw: ReadWriteAuth): AuthProvider {\n  return {\n    bindsIdentity: false,\n    authenticate() {\n      return null; // no principal model; the decision is made in the predicate.\n    },\n    async authorize(_p, req: Request, ctx: AuthContext): Promise<Decision> {\n      const fn = ctx.action === 'read' ? rw.read : rw.write;\n      if (!fn) return { allow: true };\n      const ok = await fn(req);\n      return ok ? { allow: true } : { allow: false, status: ctx.action === 'write' ? 403 : 401 };\n    },\n  };\n}\n\nfunction isProvider(x: AuthProvider | ReadWriteAuth): x is AuthProvider {\n  return typeof (x as AuthProvider).authorize === 'function';\n}\n\n/**\n * AuthProvider | {read,write} | undefined → AuthProvider | undefined (hosts reduce to a single type).\n *\n * Throws on an object that is neither, because the alternative is the worst possible answer. The\n * previous reading was \"not a provider ⇒ it must be {read,write}\", and `fromReadWrite` treats a\n * missing direction as unrestricted — so ANY unrecognised object became a provider that allows\n * everything. The realistic way to hit that is the credential map the scaffold writes:\n *\n *   createRestApi({ auth: { admin: { token: 's3cret' } } })   // looks protected, allows everyone\n *\n * That exact shape shipped once already: @gnldev/studio grew `resolveConfigAuth` for it, but\n * @gnldev/server still calls this directly, so the hole stayed open on the other host. Refusing here\n * closes it for every caller and turns a silent, invisible failure into an error at startup — the one\n * moment it can still be fixed. A caller that really wants no restrictions passes `undefined`; that\n * intent is expressible and needs no guessing.\n */\nexport function normalizeAuth(auth?: AuthProvider | ReadWriteAuth): AuthProvider | undefined {\n  if (!auth) return undefined;\n  if (isProvider(auth)) return auth;\n  const rw = auth as ReadWriteAuth;\n  // Each side that is PRESENT must be a function. The check used to be `read is fn OR write is fn`,\n  // which short-circuits: `{ read: fn, write: { admin: { token } } }` — one direction a predicate, the\n  // other a credential map, which is what a half-finished config looks like — passed here and then\n  // threw at REQUEST time, on the first write, in production. That is the silent invisible failure\n  // this whole function exists to move to startup.\n  const sides = (['read', 'write'] as const).filter((k) => rw[k] !== undefined);\n  if (sides.length > 0) {\n    const bad = sides.filter((k) => typeof rw[k] !== 'function');\n    if (bad.length === 0) return fromReadWrite(rw);\n    throw new TypeError(\n      `@gnldev/auth: \\`auth.${bad.join('\\` and \\`auth.')}\\` must be a function ` +\n      `(got ${bad.map((k) => `${k}: ${typeof rw[k]}`).join(', ')}). ` +\n      `A {read, write} pair takes predicates; a credential map like { admin: { token } } has to be ` +\n      `wrapped: \\`roleAuth({ admin: { token } })\\`. Left as it is, this authorises nothing until the ` +\n      `first request and then throws there instead.`,\n    );\n  }\n  const keys = Object.keys(auth as object).slice(0, 5).join(', ') || '(no keys)';\n  throw new TypeError(\n    `@gnldev/auth: \\`auth\\` is neither an AuthProvider (no \\`authorize\\` function) nor a {read, write} ` +\n    `pair (no \\`read\\`/\\`write\\` function). Got an object with: ${keys}. ` +\n    `If this is a credential map like { admin: { token } }, wrap it: \\`roleAuth({ admin: { token } })\\`. ` +\n    `Passing it directly would authorise every request. For no restrictions, omit \\`auth\\` entirely.`,\n  );\n}\n"]}

package/dist/gate.d.ts

@@ -0,0 +1,32 @@
+import type { AuthProvider, Principal } from './types.js';
+export interface Gate {
+    /** Is access allowed? true if there's no provider (opt-in: gate not set up → open; see makeGate in production). */
+    allow(req: Request, action: 'read' | 'write', resource?: string): Promise<boolean>;
+    /**
+     * Fine-grained variant of allow(): checks a SPECIFIC permission (e.g. 'agents:run', 'users:write').
+     *   • No provider (auth off) → true (unchanged opt-in behavior).
+     *   • EE / RBAC provider → the permission is passed through `AuthContext.permission` and matched against
+     *     the principal's EFFECTIVE permissions (explicit `permissions[]` ?? role grants) — see rbac.ts.
+     *   • Free / read-write provider → the permission is REDUCED to read/write (`:read` suffix → read, else
+     *     write) and evaluated coarsely. This makes `allowP(req,'X:write') ≡ allow(req,'write')` and
+     *     `allowP(req,'*:read') ≡ allow(req,'read')` in the free tier → no regression.
+     * A denial records its decision against the request (like allow) so `deny()` can surface status/reason.
+     */
+    allowP(req: Request, permission: string): Promise<boolean>;
+    /** Return the denial. If allow() attached its last decision to the context, use its status/reason. */
+    deny(req: Request, action: 'read' | 'write'): Response;
+}
+/**
+ * The principal authenticated during allow() (within the same request). Hosts derive the organization
+ * scope and audit actor from here → closed to header spoofing. Null if allow() hasn't been called yet.
+ */
+export declare function principalOf(req: Request): Principal | null;
+export interface GateOptions {
+    /**
+     * DELIBERATE permission for a providerless gate in production. Auth stays opt-in; but silent
+     * fail-open is impossible under NODE_ENV=production — either a provider is given or this flag is
+     * explicitly set to true (audit #2).
+     */
+    allowOpenAccess?: boolean;
+}
+export declare function makeGate(provider?: AuthProvider, opts?: GateOptions): Gate;

package/dist/gate.js

@@ -0,0 +1,122 @@
+import { isCrossSiteStateChange } from './same-site.js';
+import { bindsIdentity } from './adapter.js';
+// Per-request state, keyed by the request itself rather than stashed as a property on it. A Request
+// is somebody else's object; writing hidden fields onto it worked, but it also meant two libraries
+// could pick the same key. A WeakMap cannot collide and cannot leak — the entry dies with the request.
+const principals = new WeakMap();
+const decisions = new WeakMap();
+/**
+ * The principal authenticated during allow() (within the same request). Hosts derive the organization
+ * scope and audit actor from here → closed to header spoofing. Null if allow() hasn't been called yet.
+ */
+export function principalOf(req) {
+    return principals.get(req) ?? null;
+}
+export function makeGate(provider, opts) {
+    // Fail-open audit at SETUP time: in production, a providerless gate can only be set up with the deliberate flag.
+    // (If left to request time, the error would blow up on the first request after deploy — an early, clear failure was preferred.)
+    if (!provider && process.env.NODE_ENV === 'production' && opts?.allowOpenAccess !== true) {
+        throw new Error('auth is required in production; for deliberately open access, set allowOpenAccess: true (see @gnldev/auth makeGate / host options)');
+    }
+    // Non-production providerless gate: warn ONCE on the first request (no silent openness), then open.
+    let warnedOpen = false;
+    let warnedCrossSite = false;
+    /**
+     * The providerless decision, in ONE place.
+     *
+     * It was written inline in `allow()` only, so `allowP()` — the fine-grained entry point, and the one
+     * 23 endpoints across @gnldev/server and @gnldev/studio actually call — kept an unconditional
+     * `return true`. Which meant the cross-site block covered the coarse path and left the specific one
+     * open: a page on another site could still drive every endpoint that asks for a named permission.
+     * Two copies of a security decision is one copy too many.
+     */
+    /**
+     * Is this request a cross-site state change against a surface with NO IDENTITY to ride?
+     *
+     * The condition is about identity, not about the presence of a provider — and getting that wrong
+     * left a hole. A legacy `{read,write}` pair IS a provider after normalizeAuth, so keying on
+     * `!provider` skipped the check for it; but that pair has no principal model at all (its
+     * authenticate() is `return null` by construction), so there is no credential a cross-site page
+     * could be riding, and its predicate answers on the request alone. Measured: with
+     * `{read:()=>true, write:()=>true}` configured, a cross-site `POST /api/retention/sweep` was
+     * ALLOWED. examples/app ships exactly that shape, so it was the published example that was open.
+     *
+     * `bindsIdentity(undefined)` is false, so the providerless case is covered by the same test.
+     */
+    function crossSiteWithoutIdentity(req) {
+        if (bindsIdentity(provider) || !isCrossSiteStateChange(req))
+            return false;
+        if (!warnedCrossSite) {
+            warnedCrossSite = true;
+            console.warn('@gnldev/auth: blocked a cross-site write to a surface with no identity to authenticate ' +
+                'against. A page on another site attempted a state-changing request. Configure an auth ' +
+                'provider that binds an identity if this surface is meant to be reachable by other origins.');
+        }
+        return true;
+    }
+    function openSurfaceAllows(req) {
+        // The warning is an INSTRUCTION ("for deliberate open access use allowOpenAccess: true"), so it
+        // must stop once the instruction has been followed. It did not: the flag suppressed the
+        // production throw but not this line, so a developer who set it kept being told to set it — which
+        // teaches that the flag is inert and that this package's auth warnings can be ignored. Under
+        // NODE_ENV=production the same flag is already accepted as the whole declaration of intent; there
+        // is no reason for dev to demand it twice and then not honour it.
+        //
+        // Openness WITHOUT the flag still warns, every process, exactly as before — that is the case the
+        // message was written for.
+        if (!warnedOpen && opts?.allowOpenAccess !== true && process.env.NODE_ENV !== 'production') {
+            warnedOpen = true;
+            console.warn('@gnldev/auth: no provider given → ALL endpoints are open (opt-in gate not set up). Add auth before production; for deliberate open access use allowOpenAccess: true.');
+        }
+        return true;
+    }
+    return {
+        async allow(req, action, resource) {
+            if (crossSiteWithoutIdentity(req))
+                return false;
+            if (!provider)
+                return openSurfaceAllows(req);
+            const principal = await provider.authenticate(req);
+            if (principal)
+                principals.set(req, principal);
+            const decision = await provider.authorize(principal, req, {
+                path: new URL(req.url).pathname,
+                method: req.method,
+                action,
+                resource,
+            });
+            if (!decision.allow)
+                decisions.set(req, decision);
+            return decision.allow;
+        },
+        async allowP(req, permission) {
+            if (crossSiteWithoutIdentity(req))
+                return false;
+            if (!provider)
+                return openSurfaceAllows(req);
+            const principal = await provider.authenticate(req);
+            if (principal)
+                principals.set(req, principal);
+            // Free-tier reduction: anything ending in ':read' is a read, everything else is a write. An RBAC
+            // provider ignores `action` and matches `permission` exactly; a free provider uses this reduced action.
+            const action = permission.endsWith(':read') ? 'read' : 'write';
+            const decision = await provider.authorize(principal, req, {
+                path: new URL(req.url).pathname,
+                method: req.method,
+                action,
+                permission,
+            });
+            if (!decision.allow)
+                decisions.set(req, decision);
+            return decision.allow;
+        },
+        deny(req, action) {
+            const d = decisions.get(req);
+            const denied = d && d.allow === false ? d : undefined;
+            const status = denied?.status ?? (action === 'write' ? 403 : 401);
+            const reason = denied?.reason ?? (action === 'write' ? 'unauthorized (admin required)' : 'unauthorized');
+            return Response.json({ error: reason }, { status });
+        },
+    };
+}
+//# sourceMappingURL=gate.js.map