@btst/stack 3.0.0-rc.2 → 3.0.0-rc.4

package/dist/authorization/client.mjs

@@ -0,0 +1,152 @@
+"use client";
+import { useRef, useState, useEffect } from 'react';
+import { AuthorizationRequestValidationError } from './remote.mjs';
+import { assertJsonSafe } from '../packages/stack/src/authorization/json.mjs';
+import { useAuthContext, useIdentity } from '../packages/stack/src/context/auth.mjs';
+
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function permissionKey(permission) {
+  const request = permission;
+  const wirePermission = request?.permission?.schema === void 0 ? { id: request?.id } : { id: request.id, facts: request.facts };
+  assertJsonSafe(wirePermission);
+  return JSON.stringify(wirePermission);
+}
+function createClientAuth(config) {
+  const contractValue = config.authorization?.contract ?? config.evaluator?.contract;
+  if (!contractValue) {
+    throw new TypeError(
+      "createClientAuth requires an authorization or evaluator."
+    );
+  }
+  const contract = contractValue;
+  const runtimeAuthorization = config.authorization;
+  const runtimeEvaluator = config.evaluator;
+  let clientAuth;
+  const useIdentity$1 = () => {
+    const context = useAuthContext();
+    if (context && context.provider !== clientAuth) {
+      throw new Error(
+        "This bound useIdentity hook must be used with its createClientAuth instance on StackProvider."
+      );
+    }
+    return useIdentity();
+  };
+  const useCanRuntime = (permissionRequest) => {
+    const context = useAuthContext();
+    const contextProvider = context?.provider;
+    const contextError = context?.error;
+    const identity = context?.identity ?? null;
+    const identityPending = context?.isPending ?? true;
+    let key = "local";
+    let permissionError;
+    if (runtimeEvaluator) {
+      try {
+        key = permissionKey(permissionRequest);
+      } catch (error) {
+        permissionError = new AuthorizationRequestValidationError(error);
+        key = "invalid-remote-permission";
+      }
+    }
+    const permissionRef = useRef(permissionRequest);
+    permissionRef.current = permissionRequest;
+    const [resolved, setResolved] = useState(null);
+    useEffect(() => {
+      if (!runtimeEvaluator || permissionError || !contextProvider || contextProvider !== clientAuth || identityPending || contextError) {
+        return;
+      }
+      let cancelled = false;
+      void (async () => {
+        try {
+          const can = await runtimeEvaluator.evaluate({
+            identity,
+            permission: permissionRef.current
+          });
+          if (typeof can !== "boolean") {
+            throw new TypeError(
+              "Authorization evaluators must return a boolean."
+            );
+          }
+          if (!cancelled) {
+            setResolved({
+              can,
+              forIdentity: identity,
+              forPermission: key
+            });
+          }
+        } catch (error) {
+          if (!cancelled) {
+            setResolved({
+              can: false,
+              forIdentity: identity,
+              forPermission: key,
+              error: toError(error)
+            });
+          }
+        }
+      })();
+      return () => {
+        cancelled = true;
+      };
+    }, [contextError, contextProvider, identity, identityPending, key]);
+    if (!context || context.provider !== clientAuth) {
+      throw new Error(
+        "This bound useCan hook must be used with its createClientAuth instance on StackProvider."
+      );
+    }
+    if (context.isPending) return { can: false, isPending: true };
+    if (context.error) {
+      return { can: false, isPending: false, error: context.error };
+    }
+    if (permissionError) {
+      return { can: false, isPending: false, error: permissionError };
+    }
+    if (runtimeAuthorization) {
+      try {
+        return {
+          can: runtimeAuthorization.can(permissionRequest, context.identity),
+          isPending: false
+        };
+      } catch (error) {
+        return { can: false, isPending: false, error: toError(error) };
+      }
+    }
+    if (!resolved || resolved.forIdentity !== identity || resolved.forPermission !== key) {
+      return { can: false, isPending: true };
+    }
+    return {
+      can: resolved.can,
+      isPending: false,
+      ...resolved.error ? { error: resolved.error } : {}
+    };
+  };
+  const CanAccessRuntime = ({
+    permission: permissionRequest,
+    fallback = null,
+    loading = null,
+    children
+  }) => {
+    const state = useCanRuntime(permissionRequest);
+    if (state.error) throw state.error;
+    if (state.isPending) return loading;
+    return state.can ? children : fallback;
+  };
+  clientAuth = {
+    mode: "one-rule",
+    contract: contractValue,
+    ...config.authorization ? { authorization: config.authorization } : {},
+    async getIdentity() {
+      const identity = await config.getIdentity();
+      return contract.parseIdentity(identity);
+    },
+    ...config.loginPath ? { loginPath: config.loginPath } : {},
+    useIdentity: useIdentity$1,
+    useCan: useCanRuntime,
+    usePermission: useCanRuntime,
+    CanAccess: CanAccessRuntime
+  };
+  return clientAuth;
+}
+
+export { createClientAuth };

package/dist/authorization/index.cjs

@@ -0,0 +1,371 @@
+'use strict';
+
+const z = require('zod');
+
+const permissionSeedMarker = "__btst.authorization.permission-seed.v1";
+const permissionDescriptorMarker = "__btst.authorization.permission-descriptor.v1";
+const permissionCatalogMarker = "__btst.authorization.permission-catalog.v1";
+const authorizationContractTypes = "__btst.authorization.contract-types.v1";
+function permission(schema) {
+  const seed = {
+    schema
+  };
+  Object.defineProperty(seed, permissionSeedMarker, { value: true });
+  return Object.freeze(seed);
+}
+function isPermissionSeed(value) {
+  return typeof value === "object" && value !== null && value[permissionSeedMarker] === true;
+}
+function isPermissionDescriptor(value) {
+  return typeof value === "function" && value[permissionDescriptorMarker] === true;
+}
+function createPermissionDescriptor(id, schema) {
+  const descriptor = ((...args) => {
+    if (!schema && args.length > 0) {
+      throw new TypeError(`Permission "${id}" does not accept facts.`);
+    }
+    const facts = schema ? schema.parse(args[0]) : void 0;
+    return Object.freeze({ id, permission: descriptor, facts });
+  });
+  Object.defineProperties(descriptor, {
+    id: { value: id, enumerable: true },
+    schema: { value: schema, enumerable: true },
+    [permissionDescriptorMarker]: { value: true }
+  });
+  return Object.freeze(descriptor);
+}
+function bindPermissionTree(namespace, tree, path = "") {
+  const result = {};
+  for (const [key, value] of Object.entries(tree)) {
+    if (key === permissionSeedMarker || key === permissionDescriptorMarker || key === permissionCatalogMarker || key === authorizationContractTypes) {
+      throw new TypeError(`Permission key "${key}" is reserved.`);
+    }
+    const nextPath = path ? `${path}.${key}` : key;
+    result[key] = isPermissionSeed(value) ? createPermissionDescriptor(`${namespace}:${nextPath}`, value.schema) : bindPermissionTree(namespace, value, nextPath);
+  }
+  return Object.freeze(result);
+}
+function definePermissions(name, tree) {
+  const catalog = { ...bindPermissionTree(name, tree) };
+  Object.defineProperty(catalog, permissionCatalogMarker, {
+    value: Object.freeze({ name })
+  });
+  return Object.freeze(catalog);
+}
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function fingerprint(value) {
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= BigInt(value.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+const unsupportedPortableSchemaMessage = "Authorization contract schemas must be fully representable as JSON Schema; custom refinements, transforms, and other opaque behavior are unsupported because they cannot be derived into a stable version.";
+const portableSchemaTypes = /* @__PURE__ */ new Set([
+  "string",
+  "number",
+  "int",
+  "boolean",
+  "null",
+  "never",
+  "object",
+  "record",
+  "array",
+  "tuple",
+  "union",
+  "intersection",
+  "enum",
+  "literal",
+  "nullable",
+  "optional",
+  "nonoptional",
+  "readonly",
+  "template_literal"
+]);
+const portableCheckTypes = /* @__PURE__ */ new Set([
+  "less_than",
+  "greater_than",
+  "multiple_of",
+  "number_format",
+  "max_size",
+  "min_size",
+  "size_equals",
+  "max_length",
+  "min_length",
+  "length_equals",
+  "string_format"
+]);
+const portableLengthCheckTypes = /* @__PURE__ */ new Set([
+  "max_length",
+  "min_length",
+  "length_equals"
+]);
+const portableStringFormats = /* @__PURE__ */ new Set([
+  "email",
+  "url",
+  "emoji",
+  "uuid",
+  "guid",
+  "nanoid",
+  "cuid",
+  "cuid2",
+  "ulid",
+  "xid",
+  "ksuid",
+  "datetime",
+  "date",
+  "time",
+  "duration",
+  "ipv4",
+  "ipv6",
+  "mac",
+  "cidrv4",
+  "cidrv6",
+  "base64",
+  "base64url",
+  "json_string",
+  "e164",
+  "jwt",
+  "lowercase",
+  "uppercase",
+  "regex",
+  "starts_with",
+  "ends_with",
+  "includes",
+  "hex",
+  "hostname"
+]);
+function getLengthConstraint(definition) {
+  switch (definition.check) {
+    case "min_length":
+      return definition.minimum;
+    case "max_length":
+      return definition.maximum;
+    case "length_equals":
+      return definition.length;
+    default:
+      return void 0;
+  }
+}
+function isPortableCheckDefinition(definition) {
+  const lengthConstraint = getLengthConstraint(definition);
+  if (!portableCheckTypes.has(definition.check) || Object.values(definition).some(
+    (value) => typeof value === "number" && !Number.isFinite(value)
+  ) || definition.check === "multiple_of" && typeof definition.value === "number" && definition.value <= 0 || lengthConstraint !== void 0 && (!Number.isInteger(lengthConstraint) || lengthConstraint < 0) || definition.when !== void 0 && !portableLengthCheckTypes.has(definition.check)) {
+    return false;
+  }
+  if (definition.check !== "string_format") return true;
+  return definition.format !== void 0 && portableStringFormats.has(definition.format) && (typeof definition.fn !== "function" || definition.pattern !== void 0) && (!definition.pattern || definition.pattern.flags.length === 0) && definition.alg === void 0 && definition.hostname === void 0 && definition.protocol === void 0 && definition.normalize !== true;
+}
+function isJsonLiteral(value) {
+  return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
+}
+function inspectPortableSchema(schema, jsonSchema) {
+  const definition = schema._zod.def;
+  if (!portableSchemaTypes.has(definition.type) || "coerce" in definition && definition.coerce === true || schema._zod.traits.has("$ZodExactOptional")) {
+    return true;
+  }
+  jsonSchema["x-btst-zod-type"] = definition.type;
+  if (definition.type === "literal") {
+    const values = definition.values;
+    if (!values.every(isJsonLiteral)) return true;
+  }
+  if (definition.type === "enum") {
+    const entries = definition.entries;
+    if (!Object.values(entries).every(isJsonLiteral)) return true;
+  }
+  if (definition.type === "object") {
+    const catchall = definition.catchall;
+    if (catchall && !portableSchemaTypes.has(catchall._zod.def.type))
+      return true;
+    jsonSchema["x-btst-object-mode"] = !catchall ? "strip" : catchall._zod.def.type === "never" ? "strict" : catchall._zod.def.type === "unknown" ? "passthrough" : "catchall";
+  }
+  if ("check" in definition) {
+    if (!isPortableCheckDefinition(definition)) {
+      return true;
+    }
+  }
+  return definition.checks?.some(
+    (check) => !isPortableCheckDefinition(check._zod.def)
+  ) === true;
+}
+function toPortableJsonSchema(schema) {
+  let containsOpaqueCheck = false;
+  try {
+    const jsonSchema = z.z.toJSONSchema(schema, {
+      metadata: z.z.registry(),
+      override: ({ zodSchema, jsonSchema: jsonSchema2 }) => {
+        if (inspectPortableSchema(zodSchema, jsonSchema2)) {
+          containsOpaqueCheck = true;
+        }
+      }
+    });
+    if (containsOpaqueCheck) {
+      throw new TypeError(unsupportedPortableSchemaMessage);
+    }
+    return jsonSchema;
+  } catch (error) {
+    if (error instanceof TypeError && error.message === unsupportedPortableSchemaMessage) {
+      throw error;
+    }
+    throw new TypeError(unsupportedPortableSchemaMessage, { cause: error });
+  }
+}
+function collectDescriptors(catalogs) {
+  const descriptors = /* @__PURE__ */ new Map();
+  const collect = (tree) => {
+    for (const value of Object.values(tree)) {
+      if (isPermissionDescriptor(value)) {
+        if (descriptors.has(value.id)) {
+          throw new TypeError(`Permission "${value.id}" is registered twice.`);
+        }
+        descriptors.set(value.id, value);
+      } else if (typeof value === "object" && value !== null) {
+        collect(value);
+      }
+    }
+  };
+  for (const catalog of catalogs) collect(catalog);
+  return descriptors;
+}
+function defineAuthorizationContract(config) {
+  const permissions = Object.freeze([
+    ...config.permissions
+  ]);
+  const descriptors = collectDescriptors(permissions);
+  const permissionIds = Object.freeze([...descriptors.keys()].sort());
+  const versionSource = stableJson({
+    identity: toPortableJsonSchema(config.identity),
+    permissions: permissionIds.map((id) => {
+      const descriptor = descriptors.get(id);
+      return {
+        id,
+        facts: descriptor?.schema ? toPortableJsonSchema(descriptor.schema) : null
+      };
+    })
+  });
+  return Object.freeze({
+    identitySchema: config.identity,
+    permissions,
+    permissionIds,
+    version: `auth_${fingerprint(versionSource)}`,
+    parseIdentity(identity) {
+      if (identity === null) return null;
+      const parsed = config.identity.parse(identity);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || typeof parsed.id !== "string") {
+        throw new TypeError(
+          "Authorization identities must be objects with a string id."
+        );
+      }
+      return parsed;
+    },
+    parsePermission(permissionRequest) {
+      if (typeof permissionRequest !== "object" || permissionRequest === null || typeof permissionRequest.id !== "string") {
+        throw new TypeError("A permission request must contain a string id.");
+      }
+      const candidate = permissionRequest;
+      const descriptor = descriptors.get(candidate.id);
+      if (!descriptor) {
+        throw new TypeError(`Permission "${candidate.id}" is not registered.`);
+      }
+      if (!descriptor.schema && candidate.facts !== void 0) {
+        throw new TypeError(
+          `Permission "${candidate.id}" does not accept facts.`
+        );
+      }
+      return descriptor.schema ? descriptor(candidate.facts) : descriptor();
+    }
+  });
+}
+function createRuleTree(tree) {
+  const result = {};
+  for (const [key, value] of Object.entries(tree)) {
+    if (isPermissionDescriptor(value)) {
+      result[key] = Object.freeze({
+        allow: () => ({
+          permission: value,
+          evaluate: () => true
+        }),
+        when: (rule) => ({
+          permission: value,
+          evaluate: rule
+        })
+      });
+    } else if (typeof value === "object" && value !== null) {
+      result[key] = createRuleTree(value);
+    }
+  }
+  return result;
+}
+function defineAuthorization(config) {
+  const contractValue = config.contract ?? defineAuthorizationContract({
+    identity: config.identity,
+    permissions: config.permissions
+  });
+  const contract = contractValue;
+  const descriptors = collectDescriptors(contract.permissions);
+  const ruleCatalogs = {};
+  for (const catalog of contract.permissions) {
+    const name = catalog[permissionCatalogMarker].name;
+    if (name in ruleCatalogs) {
+      throw new TypeError(`Permission catalog "${name}" is registered twice.`);
+    }
+    ruleCatalogs[name] = createRuleTree(catalog);
+  }
+  const rules = /* @__PURE__ */ new Map();
+  for (const definition of config.rules(ruleCatalogs)) {
+    if (!descriptors.has(definition.permission.id)) {
+      throw new TypeError(
+        `Permission "${definition.permission.id}" is not registered.`
+      );
+    }
+    if (rules.has(definition.permission.id)) {
+      throw new TypeError(
+        `Permission "${definition.permission.id}" has more than one rule.`
+      );
+    }
+    rules.set(definition.permission.id, definition.evaluate);
+  }
+  return Object.freeze({
+    contract: contractValue,
+    identitySchema: contract.identitySchema,
+    permissions: contract.permissions,
+    parseIdentity(identity) {
+      return contract.parseIdentity(identity);
+    },
+    can(request, identity) {
+      const candidate = contract.parsePermission(request);
+      const parsedIdentity = contract.parseIdentity(identity);
+      const rule = rules.get(candidate.id);
+      if (!rule) return false;
+      const result = rule({
+        identity: parsedIdentity,
+        facts: candidate.facts
+      });
+      if (typeof result !== "boolean") {
+        throw new TypeError(
+          `Authorization rule for "${candidate.id}" must return a boolean.`
+        );
+      }
+      return result;
+    }
+  });
+}
+function isPermissionRequest(value) {
+  return typeof value === "object" && value !== null && typeof value.id === "string" && isPermissionDescriptor(value.permission);
+}
+
+exports.defineAuthorization = defineAuthorization;
+exports.defineAuthorizationContract = defineAuthorizationContract;
+exports.definePermissions = definePermissions;
+exports.isPermissionRequest = isPermissionRequest;
+exports.permission = permission;