@daltonr/authwrite-hateoas 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import type { AuthEvaluator, Subject, Resource, Action } from '@daltonr/authwrite-core';
+export interface LinkTemplate {
+    /** The URL for this action. May be a plain string or a pre-resolved href. */
+    href: string;
+    /** HTTP method. Defaults to 'GET'. */
+    method?: string;
+    /** Human-readable label, useful for UI rendering. */
+    title?: string;
+    /** Any additional properties (templated, type, etc.) */
+    [key: string]: unknown;
+}
+/** A map of action name → link. Only permitted actions are present. */
+export type LinkMap = Record<string, LinkTemplate>;
+export interface BuildLinksConfig<S extends Subject = Subject, R extends Resource = Resource> {
+    engine: AuthEvaluator<S, R>;
+    subject: S;
+    resource?: R;
+    /**
+     * Map of action name → link template.
+     * Only entries whose action is permitted will appear in the result.
+     */
+    actions: Record<Action, LinkTemplate>;
+}
+/**
+ * Evaluates every action in `config.actions` and returns a `LinkMap`
+ * containing only the links the subject is permitted to follow.
+ *
+ * ```typescript
+ * const links = await buildLinks({
+ *   engine,
+ *   subject,
+ *   resource,
+ *   actions: {
+ *     read:    { href: `/documents/${id}`,         method: 'GET' },
+ *     write:   { href: `/documents/${id}`,         method: 'PUT' },
+ *     delete:  { href: `/documents/${id}`,         method: 'DELETE' },
+ *     archive: { href: `/documents/${id}/archive`, method: 'POST' },
+ *   },
+ * })
+ * // → only links whose policy decision was allowed: true
+ * ```
+ */
+export declare function buildLinks<S extends Subject = Subject, R extends Resource = Resource>(config: BuildLinksConfig<S, R>): Promise<LinkMap>;
+export interface EmbedLinksConfig<S extends Subject = Subject, R extends Resource = Resource> extends BuildLinksConfig<S, R> {
+    /**
+     * A `self` link added unconditionally — it is not subject to policy
+     * evaluation since the resource has already been fetched and returned.
+     */
+    self?: LinkTemplate;
+}
+/**
+ * Builds permission-aware links and merges them into `data` as a `_links`
+ * property, following HAL (application/hal+json) conventions.
+ *
+ * ```typescript
+ * const body = await embedLinks(document, {
+ *   engine, subject, resource: document,
+ *   self: { href: `/documents/${document.id}`, method: 'GET' },
+ *   actions: {
+ *     write:   { href: `/documents/${document.id}`, method: 'PUT' },
+ *     delete:  { href: `/documents/${document.id}`, method: 'DELETE' },
+ *   },
+ * })
+ * // → { ...document, _links: { self: {...}, write: {...} } }
+ * //   (delete absent — not permitted)
+ * ```
+ */
+export declare function embedLinks<T extends object, S extends Subject = Subject, R extends Resource = Resource>(data: T, config: EmbedLinksConfig<S, R>): Promise<T & {
+    _links: LinkMap;
+}>;
+/**
+ * Synchronous variant for cases where you have already called `engine.permissions()`
+ * and want to build links without an additional async round-trip.
+ *
+ * ```typescript
+ * const perms = await engine.permissions(subject, resource, ['read', 'write', 'delete'])
+ * const links = linksFromDecisions(perms, actionTemplates)
+ * ```
+ */
+export declare function linksFromDecisions(permissions: Record<string, boolean>, actions: Record<Action, LinkTemplate>): LinkMap;

package/dist/index.js

@@ -0,0 +1,78 @@
+// ─── buildLinks ───────────────────────────────────────────────────────────────
+/**
+ * Evaluates every action in `config.actions` and returns a `LinkMap`
+ * containing only the links the subject is permitted to follow.
+ *
+ * ```typescript
+ * const links = await buildLinks({
+ *   engine,
+ *   subject,
+ *   resource,
+ *   actions: {
+ *     read:    { href: `/documents/${id}`,         method: 'GET' },
+ *     write:   { href: `/documents/${id}`,         method: 'PUT' },
+ *     delete:  { href: `/documents/${id}`,         method: 'DELETE' },
+ *     archive: { href: `/documents/${id}/archive`, method: 'POST' },
+ *   },
+ * })
+ * // → only links whose policy decision was allowed: true
+ * ```
+ */
+export async function buildLinks(config) {
+    const actionNames = Object.keys(config.actions);
+    const permitted = config.resource !== undefined
+        ? await config.engine.permissions(config.subject, config.resource, actionNames)
+        : await config.engine.permissions(config.subject, actionNames);
+    const links = {};
+    for (const action of actionNames) {
+        if (permitted[action]) {
+            links[action] = config.actions[action];
+        }
+    }
+    return links;
+}
+/**
+ * Builds permission-aware links and merges them into `data` as a `_links`
+ * property, following HAL (application/hal+json) conventions.
+ *
+ * ```typescript
+ * const body = await embedLinks(document, {
+ *   engine, subject, resource: document,
+ *   self: { href: `/documents/${document.id}`, method: 'GET' },
+ *   actions: {
+ *     write:   { href: `/documents/${document.id}`, method: 'PUT' },
+ *     delete:  { href: `/documents/${document.id}`, method: 'DELETE' },
+ *   },
+ * })
+ * // → { ...document, _links: { self: {...}, write: {...} } }
+ * //   (delete absent — not permitted)
+ * ```
+ */
+export async function embedLinks(data, config) {
+    const permitted = await buildLinks(config);
+    const _links = {};
+    if (config.self)
+        _links['self'] = config.self;
+    Object.assign(_links, permitted);
+    return { ...data, _links };
+}
+// ─── Decision-based link filtering (sync, from pre-fetched decisions) ─────────
+/**
+ * Synchronous variant for cases where you have already called `engine.permissions()`
+ * and want to build links without an additional async round-trip.
+ *
+ * ```typescript
+ * const perms = await engine.permissions(subject, resource, ['read', 'write', 'delete'])
+ * const links = linksFromDecisions(perms, actionTemplates)
+ * ```
+ */
+export function linksFromDecisions(permissions, actions) {
+    const links = {};
+    for (const [action, template] of Object.entries(actions)) {
+        if (permissions[action]) {
+            links[action] = template;
+        }
+    }
+    return links;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkCA,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAG9B,MAA8B;IAC9B,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAE/C,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,KAAK,SAAS;QAC7C,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC;QAC/E,CAAC,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAA;IAEhE,MAAM,KAAK,GAAY,EAAE,CAAA;IACzB,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACxC,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAI9B,IAAO,EAAE,MAA8B;IACvC,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAA;IAE1C,MAAM,MAAM,GAAY,EAAE,CAAA;IAC1B,IAAI,MAAM,CAAC,IAAI;QAAE,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAA;IAC7C,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAEhC,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED,iFAAiF;AAEjF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAoC,EACpC,OAAyC;IAEzC,MAAM,KAAK,GAAY,EAAE,CAAA;IACzB,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;YACxB,KAAK,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAA;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@daltonr/authwrite-hateoas",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "HATEOAS link building for Authwrite — permission-aware hypermedia links from policy decisions.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardadalton/authwrite.git",
+    "directory": "packages/hateoas"
+  },
+  "keywords": ["authorization", "authz", "hateoas", "hal", "hypermedia", "links"],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepublishOnly": "test -d dist && echo 'dist already built, skipping' || (npm run clean && npm run build)"
+  },
+  "dependencies": {
+    "@daltonr/authwrite-core": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+import type { AuthEvaluator, Subject, Resource, Action } from '@daltonr/authwrite-core'
+
+// ─── Link types ───────────────────────────────────────────────────────────────
+
+export interface LinkTemplate {
+  /** The URL for this action. May be a plain string or a pre-resolved href. */
+  href:    string
+  /** HTTP method. Defaults to 'GET'. */
+  method?: string
+  /** Human-readable label, useful for UI rendering. */
+  title?:  string
+  /** Any additional properties (templated, type, etc.) */
+  [key: string]: unknown
+}
+
+/** A map of action name → link. Only permitted actions are present. */
+export type LinkMap = Record<string, LinkTemplate>
+
+// ─── buildLinks config ────────────────────────────────────────────────────────
+
+export interface BuildLinksConfig<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+> {
+  engine:   AuthEvaluator<S, R>
+  subject:  S
+  resource?: R
+  /**
+   * Map of action name → link template.
+   * Only entries whose action is permitted will appear in the result.
+   */
+  actions: Record<Action, LinkTemplate>
+}
+
+// ─── buildLinks ───────────────────────────────────────────────────────────────
+
+/**
+ * Evaluates every action in `config.actions` and returns a `LinkMap`
+ * containing only the links the subject is permitted to follow.
+ *
+ * ```typescript
+ * const links = await buildLinks({
+ *   engine,
+ *   subject,
+ *   resource,
+ *   actions: {
+ *     read:    { href: `/documents/${id}`,         method: 'GET' },
+ *     write:   { href: `/documents/${id}`,         method: 'PUT' },
+ *     delete:  { href: `/documents/${id}`,         method: 'DELETE' },
+ *     archive: { href: `/documents/${id}/archive`, method: 'POST' },
+ *   },
+ * })
+ * // → only links whose policy decision was allowed: true
+ * ```
+ */
+export async function buildLinks<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+>(config: BuildLinksConfig<S, R>): Promise<LinkMap> {
+  const actionNames = Object.keys(config.actions)
+
+  const permitted = config.resource !== undefined
+    ? await config.engine.permissions(config.subject, config.resource, actionNames)
+    : await config.engine.permissions(config.subject, actionNames)
+
+  const links: LinkMap = {}
+  for (const action of actionNames) {
+    if (permitted[action]) {
+      links[action] = config.actions[action]
+    }
+  }
+
+  return links
+}
+
+// ─── embedLinks ───────────────────────────────────────────────────────────────
+
+export interface EmbedLinksConfig<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+> extends BuildLinksConfig<S, R> {
+  /**
+   * A `self` link added unconditionally — it is not subject to policy
+   * evaluation since the resource has already been fetched and returned.
+   */
+  self?: LinkTemplate
+}
+
+/**
+ * Builds permission-aware links and merges them into `data` as a `_links`
+ * property, following HAL (application/hal+json) conventions.
+ *
+ * ```typescript
+ * const body = await embedLinks(document, {
+ *   engine, subject, resource: document,
+ *   self: { href: `/documents/${document.id}`, method: 'GET' },
+ *   actions: {
+ *     write:   { href: `/documents/${document.id}`, method: 'PUT' },
+ *     delete:  { href: `/documents/${document.id}`, method: 'DELETE' },
+ *   },
+ * })
+ * // → { ...document, _links: { self: {...}, write: {...} } }
+ * //   (delete absent — not permitted)
+ * ```
+ */
+export async function embedLinks<
+  T extends object,
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+>(data: T, config: EmbedLinksConfig<S, R>): Promise<T & { _links: LinkMap }> {
+  const permitted = await buildLinks(config)
+
+  const _links: LinkMap = {}
+  if (config.self) _links['self'] = config.self
+  Object.assign(_links, permitted)
+
+  return { ...data, _links }
+}
+
+// ─── Decision-based link filtering (sync, from pre-fetched decisions) ─────────
+
+/**
+ * Synchronous variant for cases where you have already called `engine.permissions()`
+ * and want to build links without an additional async round-trip.
+ *
+ * ```typescript
+ * const perms = await engine.permissions(subject, resource, ['read', 'write', 'delete'])
+ * const links = linksFromDecisions(perms, actionTemplates)
+ * ```
+ */
+export function linksFromDecisions(
+  permissions: Record<string, boolean>,
+  actions:     Record<Action, LinkTemplate>,
+): LinkMap {
+  const links: LinkMap = {}
+  for (const [action, template] of Object.entries(actions)) {
+    if (permissions[action]) {
+      links[action] = template
+    }
+  }
+  return links
+}