@atlasauth/authz 0.1.0

package/dist/claims.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The minimal, structural view of session claims the authorization primitive
+ * needs. Every SDK has its own richer `SessionClaims` (the backend verifier, the
+ * React session, the Next.js middleware); each is assignable to this shape, so
+ * they can all feed the SAME `evaluate()` without this package depending on any
+ * of them. Keeping it structural is deliberate — it is the seam that lets one
+ * primitive serve server, edge, and browser alike.
+ */
+export interface AuthzClaims {
+    /** The active organization, if the session has one selected. */
+    org_id?: string | null;
+    /** The user's role key in the active organization (e.g. `org:admin`). */
+    org_role?: string | null;
+    /**
+     * The permission keys the active-org role holds — the union of the role's
+     * direct permissions and any granted through group membership, exactly as the
+     * token was minted. Authorization reads this set; it never re-derives it.
+     */
+    org_permissions?: readonly string[] | null;
+    /**
+     * §billing — the active plan slug (Clerk `has({plan})`), minted as `pla` only
+     * when the subject is entitled (its org's plan in a B2B org, else the user's).
+     * An unsubscribed token omits it. Unlike org permissions this needs NO active
+     * organization to evaluate.
+     */
+    pla?: string | null;
+    /** §billing — the granted feature keys (Clerk `has({feature})`), minted as `fea`. */
+    fea?: readonly string[] | null;
+}

package/dist/claims.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@atlasauth/authz` — the framework-agnostic authorization primitive shared by
+ * every Atlas SDK. Zero dependencies, no DOM, no Node: one `evaluate()` and one
+ * `ProtectCondition` so a permission check means the same thing in a browser, an
+ * edge middleware, and a Node server.
+ */
+export type { AuthzClaims } from './claims';
+export { type ProtectCondition, type ProtectOutcome, type ProtectReason, evaluate, hasFromClaims, protectFromClaims, ForbiddenError, } from './protect';
+export { ROLE_KEY_PATTERN, PERMISSION_KEY_PATTERN, isRoleKey, isPermissionKey, } from './keys';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPermissionKey = exports.isRoleKey = exports.PERMISSION_KEY_PATTERN = exports.ROLE_KEY_PATTERN = exports.ForbiddenError = exports.protectFromClaims = exports.hasFromClaims = exports.evaluate = void 0;
+var protect_1 = require("./protect");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return protect_1.evaluate; } });
+Object.defineProperty(exports, "hasFromClaims", { enumerable: true, get: function () { return protect_1.hasFromClaims; } });
+Object.defineProperty(exports, "protectFromClaims", { enumerable: true, get: function () { return protect_1.protectFromClaims; } });
+Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return protect_1.ForbiddenError; } });
+var keys_1 = require("./keys");
+Object.defineProperty(exports, "ROLE_KEY_PATTERN", { enumerable: true, get: function () { return keys_1.ROLE_KEY_PATTERN; } });
+Object.defineProperty(exports, "PERMISSION_KEY_PATTERN", { enumerable: true, get: function () { return keys_1.PERMISSION_KEY_PATTERN; } });
+Object.defineProperty(exports, "isRoleKey", { enumerable: true, get: function () { return keys_1.isRoleKey; } });
+Object.defineProperty(exports, "isPermissionKey", { enumerable: true, get: function () { return keys_1.isPermissionKey; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAOA,qCAQmB;AAJjB,mGAAA,QAAQ,OAAA;AACR,wGAAA,aAAa,OAAA;AACb,4GAAA,iBAAiB,OAAA;AACjB,yGAAA,cAAc,OAAA;AAEhB,+BAKgB;AAJd,wGAAA,gBAAgB,OAAA;AAChB,8GAAA,sBAAsB,OAAA;AACtB,iGAAA,SAAS,OAAA;AACT,uGAAA,eAAe,OAAA"}

package/dist/keys.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Role and permission KEY SHAPES — the single definition every layer shares.
+ *
+ * The two shapes are deliberately different, and the difference is meaningful:
+ *
+ *   ROLE keys are `org:<segment>`      — e.g. `org:admin`, `org:member`.
+ *   PERMISSION keys are `org:<resource>:<action>` — e.g. `org:billing:manage`.
+ *
+ * A role names WHO someone is; a permission names WHAT they may do to a
+ * resource. That is why `<Protect role="org:admin">` and
+ * `<Protect permission="org:billing:manage">` both type-check but read
+ * differently — the arity of the key tells you which you are looking at.
+ *
+ * The full creation-time rules (reserved `sys_` prefix, immutability, length)
+ * live in `@atlas/core`'s validator, which imports these patterns so the two can
+ * never drift.
+ */
+/** `org:` then one lowercase segment. Matches a role key like `org:admin`. */
+export declare const ROLE_KEY_PATTERN: RegExp;
+/** `org:<resource>:<action>`. Matches a permission key like `org:billing:manage`. */
+export declare const PERMISSION_KEY_PATTERN: RegExp;
+/** True for a well-shaped role key (`org:admin`), false otherwise. */
+export declare function isRoleKey(key: string): boolean;
+/** True for a well-shaped permission key (`org:billing:manage`), false otherwise. */
+export declare function isPermissionKey(key: string): boolean;

package/dist/keys.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Role and permission KEY SHAPES — the single definition every layer shares.
+ *
+ * The two shapes are deliberately different, and the difference is meaningful:
+ *
+ *   ROLE keys are `org:<segment>`      — e.g. `org:admin`, `org:member`.
+ *   PERMISSION keys are `org:<resource>:<action>` — e.g. `org:billing:manage`.
+ *
+ * A role names WHO someone is; a permission names WHAT they may do to a
+ * resource. That is why `<Protect role="org:admin">` and
+ * `<Protect permission="org:billing:manage">` both type-check but read
+ * differently — the arity of the key tells you which you are looking at.
+ *
+ * The full creation-time rules (reserved `sys_` prefix, immutability, length)
+ * live in `@atlas/core`'s validator, which imports these patterns so the two can
+ * never drift.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_KEY_PATTERN = exports.ROLE_KEY_PATTERN = void 0;
+exports.isRoleKey = isRoleKey;
+exports.isPermissionKey = isPermissionKey;
+/** `org:` then one lowercase segment. Matches a role key like `org:admin`. */
+exports.ROLE_KEY_PATTERN = /^org:[a-z][a-z0-9_]{1,31}$/;
+/** `org:<resource>:<action>`. Matches a permission key like `org:billing:manage`. */
+exports.PERMISSION_KEY_PATTERN = /^org:[a-z][a-z0-9_]{1,31}:[a-z][a-z0-9_]{1,31}$/;
+/** True for a well-shaped role key (`org:admin`), false otherwise. */
+function isRoleKey(key) {
+    return exports.ROLE_KEY_PATTERN.test(key);
+}
+/** True for a well-shaped permission key (`org:billing:manage`), false otherwise. */
+function isPermissionKey(key) {
+    return exports.PERMISSION_KEY_PATTERN.test(key);
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AASH,8BAEC;AAGD,0CAEC;AAdD,8EAA8E;AACjE,QAAA,gBAAgB,GAAG,4BAA4B,CAAC;AAE7D,qFAAqF;AACxE,QAAA,sBAAsB,GAAG,iDAAiD,CAAC;AAExF,sEAAsE;AACtE,SAAgB,SAAS,CAAC,GAAW;IACnC,OAAO,wBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,qFAAqF;AACrF,SAAgB,eAAe,CAAC,GAAW;IACzC,OAAO,8BAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC"}

package/dist/protect.d.ts

@@ -0,0 +1,64 @@
+import type { AuthzClaims } from './claims';
+/**
+ * The ONE authorization condition every Atlas SDK evaluates — `@atlasauth/backend`,
+ * `@atlasauth/nextjs`, `@atlasauth/react`, `@atlasauth/react-native`, and `@atlasauth/js` all
+ * import this exact shape and the `evaluate()` below. Before this package the
+ * same `has()` meant different things on different surfaces (React understood
+ * all four fields; Next.js understood only two; the backend had no `has()` at
+ * all). Centralizing the contract here is what makes a check portable across
+ * client and server.
+ */
+export interface ProtectCondition {
+    /** A single permission the ACTIVE organization role must hold. */
+    permission?: string;
+    /** An exact role in the active organization. */
+    role?: string;
+    /** Any of these permissions (OR). */
+    anyPermission?: readonly string[];
+    /** All of these permissions (AND). */
+    allPermissions?: readonly string[];
+    /** The active billing plan (Clerk `has({ plan })`) — matches the `pla` claim.
+     *  Needs NO active organization: it is the subject's entitlement. */
+    plan?: string;
+    /** A granted feature (Clerk `has({ feature })`) — an entry in the `fea` claim. */
+    feature?: string;
+}
+export type ProtectReason = 'signed_out' | 'no_organization' | 'missing_permission' | 'missing_entitlement';
+export type ProtectOutcome = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: ProtectReason;
+};
+/**
+ * Whether `claims` satisfy `condition`, with a reason when they do not.
+ *
+ * An empty condition means "signed in", which is the common case and reads
+ * naturally as `<Protect>` / `has({})`. Requiring an explicit `signedIn` flag
+ * would make the simplest usage the noisiest.
+ *
+ * A user with no active organization FAILS any organization condition rather
+ * than passing it vacuously: `allPermissions: []` against no org must not render
+ * an admin panel just because the empty set is trivially satisfied. (This is the
+ * exact case where the old Next.js `has()` and React `has()` disagreed — they
+ * now share this one rule.)
+ */
+export declare function evaluate(claims: AuthzClaims | null | undefined, condition?: ProtectCondition): ProtectOutcome;
+/** The boolean form — the primitive behind every surface's `has(condition)`. */
+export declare function hasFromClaims(claims: AuthzClaims | null | undefined, condition?: ProtectCondition): boolean;
+/**
+ * The error `protect()` throws when a condition is not met. Carrying the reason
+ * (and the failed condition) lets a server framework map it to the right status:
+ * `signed_out` → 401, everything else → 403/404 per the app's convention.
+ */
+export declare class ForbiddenError extends Error {
+    readonly reason: ProtectReason;
+    readonly condition: ProtectCondition;
+    constructor(reason: ProtectReason, condition: ProtectCondition);
+}
+/**
+ * Assert a condition, throwing `ForbiddenError` when it fails. The imperative
+ * companion to `hasFromClaims` — a server route calls this to hard-stop a
+ * request, the same way Clerk's `auth().protect()` does.
+ */
+export declare function protectFromClaims(claims: AuthzClaims | null | undefined, condition?: ProtectCondition): void;

package/dist/protect.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForbiddenError = void 0;
+exports.evaluate = evaluate;
+exports.hasFromClaims = hasFromClaims;
+exports.protectFromClaims = protectFromClaims;
+/** The condition fields that require an active organization to satisfy. */
+function wantsOrgContext(condition) {
+    return (condition.permission !== undefined ||
+        condition.role !== undefined ||
+        condition.anyPermission !== undefined ||
+        condition.allPermissions !== undefined);
+}
+/**
+ * Whether `claims` satisfy `condition`, with a reason when they do not.
+ *
+ * An empty condition means "signed in", which is the common case and reads
+ * naturally as `<Protect>` / `has({})`. Requiring an explicit `signedIn` flag
+ * would make the simplest usage the noisiest.
+ *
+ * A user with no active organization FAILS any organization condition rather
+ * than passing it vacuously: `allPermissions: []` against no org must not render
+ * an admin panel just because the empty set is trivially satisfied. (This is the
+ * exact case where the old Next.js `has()` and React `has()` disagreed — they
+ * now share this one rule.)
+ */
+function evaluate(claims, condition = {}) {
+    if (!claims)
+        return { allowed: false, reason: 'signed_out' };
+    // Entitlement (plan/feature) is the subject's own — its org's in a B2B org,
+    // else the user's — minted as `pla`/`fea`. It does NOT require an active
+    // organization, so it is checked before the org-context gate below.
+    if (condition.plan !== undefined && claims.pla !== condition.plan) {
+        return { allowed: false, reason: 'missing_entitlement' };
+    }
+    if (condition.feature !== undefined && !(claims.fea ?? []).includes(condition.feature)) {
+        return { allowed: false, reason: 'missing_entitlement' };
+    }
+    if (!wantsOrgContext(condition))
+        return { allowed: true };
+    if (!claims.org_id)
+        return { allowed: false, reason: 'no_organization' };
+    const held = new Set(claims.org_permissions ?? []);
+    if (condition.role !== undefined && claims.org_role !== condition.role) {
+        return { allowed: false, reason: 'missing_permission' };
+    }
+    if (condition.permission !== undefined && !held.has(condition.permission)) {
+        return { allowed: false, reason: 'missing_permission' };
+    }
+    if (condition.anyPermission && !condition.anyPermission.some((p) => held.has(p))) {
+        return { allowed: false, reason: 'missing_permission' };
+    }
+    if (condition.allPermissions && !condition.allPermissions.every((p) => held.has(p))) {
+        return { allowed: false, reason: 'missing_permission' };
+    }
+    return { allowed: true };
+}
+/** The boolean form — the primitive behind every surface's `has(condition)`. */
+function hasFromClaims(claims, condition = {}) {
+    return evaluate(claims, condition).allowed;
+}
+/**
+ * The error `protect()` throws when a condition is not met. Carrying the reason
+ * (and the failed condition) lets a server framework map it to the right status:
+ * `signed_out` → 401, everything else → 403/404 per the app's convention.
+ */
+class ForbiddenError extends Error {
+    reason;
+    condition;
+    constructor(reason, condition) {
+        super(reason === 'signed_out'
+            ? 'Not signed in.'
+            : reason === 'no_organization'
+                ? 'No active organization for this authorization check.'
+                : reason === 'missing_entitlement'
+                    ? 'Missing the required plan or feature.'
+                    : 'Missing the required permission or role.');
+        this.name = 'ForbiddenError';
+        this.reason = reason;
+        this.condition = condition;
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+/**
+ * Assert a condition, throwing `ForbiddenError` when it fails. The imperative
+ * companion to `hasFromClaims` — a server route calls this to hard-stop a
+ * request, the same way Clerk's `auth().protect()` does.
+ */
+function protectFromClaims(claims, condition = {}) {
+    const outcome = evaluate(claims, condition);
+    if (!outcome.allowed)
+        throw new ForbiddenError(outcome.reason, condition);
+}
+//# sourceMappingURL=protect.js.map

package/dist/protect.js.map

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

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@atlasauth/authz",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}