@daltonr/authwrite-loader-yaml 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { AuthContext, PolicyLoader, Resource, Subject } from '@daltonr/authwrite-core';
+export interface RuleFn<S extends Subject = Subject, R extends Resource = Resource> {
+    match: (ctx: AuthContext<S, R>) => boolean;
+    condition?: (ctx: AuthContext<S, R>) => boolean;
+}
+export type RuleRegistry<S extends Subject = Subject, R extends Resource = Resource> = Record<string, RuleFn<S, R>>;
+export interface FileLoaderConfig<S extends Subject = Subject, R extends Resource = Resource> {
+    /** Absolute or relative path to a .yaml, .yml, or .json policy file. */
+    path: string;
+    /** Maps rule IDs (from the file) to their match/condition implementations. */
+    rules: RuleRegistry<S, R>;
+}
+export declare function createFileLoader<S extends Subject = Subject, R extends Resource = Resource>(config: FileLoaderConfig<S, R>): PolicyLoader<S, R>;

package/dist/index.js

@@ -0,0 +1,100 @@
+import { readFile } from 'node:fs/promises';
+import { watch } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function validate(raw) {
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Policy file must be a YAML/JSON object');
+    }
+    const p = raw;
+    if (typeof p['id'] !== 'string' || !p['id']) {
+        throw new Error('Policy file must have a string "id" field');
+    }
+    if (p['defaultEffect'] !== 'allow' && p['defaultEffect'] !== 'deny') {
+        throw new Error(`"defaultEffect" must be "allow" or "deny", got: ${JSON.stringify(p['defaultEffect'])}`);
+    }
+    if (!Array.isArray(p['rules'])) {
+        throw new Error('Policy file must have a "rules" array');
+    }
+    return p;
+}
+function mergeRules(serializableRules, registry, context) {
+    return serializableRules.map(sr => {
+        const fn = registry[sr.id];
+        if (!fn) {
+            throw new Error(`Rule "${sr.id}" (from ${context}) has no implementation in the registry. ` +
+                `Add an entry for "${sr.id}" to the rules registry.`);
+        }
+        const rule = {
+            id: sr.id,
+            match: fn.match,
+            allow: sr.allow,
+            deny: sr.deny,
+        };
+        if (sr.description !== undefined)
+            rule.description = sr.description;
+        if (sr.priority !== undefined)
+            rule.priority = sr.priority;
+        if (fn.condition !== undefined)
+            rule.condition = fn.condition;
+        return rule;
+    });
+}
+function mergeFieldRules(serializableFieldRules, registry) {
+    return serializableFieldRules.map(sfr => {
+        const fn = registry[sfr.id];
+        if (!fn) {
+            throw new Error(`FieldRule "${sfr.id}" has no implementation in the registry. ` +
+                `Add an entry for "${sfr.id}" to the rules registry.`);
+        }
+        return {
+            id: sfr.id,
+            match: fn.match,
+            expose: sfr.expose,
+            redact: sfr.redact,
+        };
+    });
+}
+function buildPolicy(content, registry) {
+    const raw = parseYaml(content);
+    const serializable = validate(raw);
+    const policy = {
+        id: serializable.id,
+        defaultEffect: serializable.defaultEffect,
+        rules: mergeRules(serializable.rules, registry, 'rules'),
+    };
+    if (serializable.version !== undefined)
+        policy.version = serializable.version;
+    if (serializable.description !== undefined)
+        policy.description = serializable.description;
+    if (serializable.fieldRules && serializable.fieldRules.length > 0) {
+        policy.fieldRules = mergeFieldRules(serializable.fieldRules, registry);
+    }
+    return policy;
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+export function createFileLoader(config) {
+    async function load() {
+        const content = await readFile(config.path, 'utf-8');
+        return buildPolicy(content, config.rules);
+    }
+    function watchFile(cb) {
+        // Debounce: many editors write files in multiple events for a single save.
+        let debounceTimer;
+        watch(config.path, () => {
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(async () => {
+                try {
+                    const policy = await load();
+                    cb(policy);
+                }
+                catch {
+                    // Swallow parse errors during watch — the file may be mid-write.
+                    // The next fs event (when the write completes) will retry.
+                }
+            }, 50);
+        });
+    }
+    return { load, watch: watchFile };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@daltonr/authwrite-loader-yaml",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "YAML/JSON file-based policy loader for AuthEngine.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/richardadalton/authwrite.git",
+    "directory": "packages/loader-yaml"
+  },
+  "keywords": ["authorization", "authz", "loader", "policy", "yaml", "gitops"],
+  "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": "*"
+  },
+  "peerDependencies": {
+    "yaml": ">=2.0.0"
+  },
+  "devDependencies": {
+    "yaml": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,196 @@
+import { readFile } from 'node:fs/promises'
+import { watch } from 'node:fs'
+import { parse as parseYaml } from 'yaml'
+import type {
+  Action,
+  AuthContext,
+  FieldRule,
+  PolicyDefinition,
+  PolicyLoader,
+  PolicyRule,
+  Resource,
+  Subject,
+} from '@daltonr/authwrite-core'
+
+// ─── Serializable file schema ─────────────────────────────────────────────────
+//
+// Rules and fieldRules in the file contain everything EXCEPT functions.
+// The match/condition functions are provided through the RuleRegistry.
+
+interface SerializableRule {
+  id: string
+  description?: string
+  priority?: number
+  allow?: Action[]
+  deny?: Action[]
+}
+
+interface SerializableFieldRule {
+  id: string
+  expose: string[]
+  redact: string[]
+}
+
+interface SerializablePolicy {
+  id: string
+  version?: string
+  description?: string
+  defaultEffect: 'allow' | 'deny'
+  rules: SerializableRule[]
+  fieldRules?: SerializableFieldRule[]
+}
+
+// ─── Rule registry ────────────────────────────────────────────────────────────
+//
+// Maps rule IDs to their runtime functions. Entries may be used by both
+// rules and fieldRules — the match/condition shape is the same for both.
+
+export interface RuleFn<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+> {
+  match: (ctx: AuthContext<S, R>) => boolean
+  condition?: (ctx: AuthContext<S, R>) => boolean
+}
+
+export type RuleRegistry<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+> = Record<string, RuleFn<S, R>>
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface FileLoaderConfig<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+> {
+  /** Absolute or relative path to a .yaml, .yml, or .json policy file. */
+  path: string
+  /** Maps rule IDs (from the file) to their match/condition implementations. */
+  rules: RuleRegistry<S, R>
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function validate(raw: unknown): SerializablePolicy {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('Policy file must be a YAML/JSON object')
+  }
+
+  const p = raw as Record<string, unknown>
+
+  if (typeof p['id'] !== 'string' || !p['id']) {
+    throw new Error('Policy file must have a string "id" field')
+  }
+  if (p['defaultEffect'] !== 'allow' && p['defaultEffect'] !== 'deny') {
+    throw new Error(`"defaultEffect" must be "allow" or "deny", got: ${JSON.stringify(p['defaultEffect'])}`)
+  }
+  if (!Array.isArray(p['rules'])) {
+    throw new Error('Policy file must have a "rules" array')
+  }
+
+  return p as unknown as SerializablePolicy
+}
+
+function mergeRules<S extends Subject, R extends Resource>(
+  serializableRules: SerializableRule[],
+  registry: RuleRegistry<S, R>,
+  context: 'rules' | 'fieldRules',
+): PolicyRule<S, R>[] {
+  return serializableRules.map(sr => {
+    const fn = registry[sr.id]
+    if (!fn) {
+      throw new Error(
+        `Rule "${sr.id}" (from ${context}) has no implementation in the registry. ` +
+        `Add an entry for "${sr.id}" to the rules registry.`
+      )
+    }
+    const rule: PolicyRule<S, R> = {
+      id:          sr.id,
+      match:       fn.match,
+      allow:       sr.allow,
+      deny:        sr.deny,
+    }
+    if (sr.description !== undefined) rule.description = sr.description
+    if (sr.priority    !== undefined) rule.priority    = sr.priority
+    if (fn.condition   !== undefined) rule.condition   = fn.condition
+    return rule
+  })
+}
+
+function mergeFieldRules<S extends Subject, R extends Resource>(
+  serializableFieldRules: SerializableFieldRule[],
+  registry: RuleRegistry<S, R>,
+): FieldRule<S, R>[] {
+  return serializableFieldRules.map(sfr => {
+    const fn = registry[sfr.id]
+    if (!fn) {
+      throw new Error(
+        `FieldRule "${sfr.id}" has no implementation in the registry. ` +
+        `Add an entry for "${sfr.id}" to the rules registry.`
+      )
+    }
+    return {
+      id:     sfr.id,
+      match:  fn.match,
+      expose: sfr.expose,
+      redact: sfr.redact,
+    }
+  })
+}
+
+function buildPolicy<S extends Subject, R extends Resource>(
+  content: string,
+  registry: RuleRegistry<S, R>,
+): PolicyDefinition<S, R> {
+  const raw = parseYaml(content)
+  const serializable = validate(raw)
+
+  const policy: PolicyDefinition<S, R> = {
+    id:            serializable.id,
+    defaultEffect: serializable.defaultEffect,
+    rules:         mergeRules(serializable.rules, registry, 'rules'),
+  }
+
+  if (serializable.version     !== undefined) policy.version     = serializable.version
+  if (serializable.description !== undefined) policy.description = serializable.description
+
+  if (serializable.fieldRules && serializable.fieldRules.length > 0) {
+    policy.fieldRules = mergeFieldRules(serializable.fieldRules, registry)
+  }
+
+  return policy
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createFileLoader<
+  S extends Subject = Subject,
+  R extends Resource = Resource,
+>(config: FileLoaderConfig<S, R>): PolicyLoader<S, R> {
+
+  async function load(): Promise<PolicyDefinition<S, R>> {
+    const content = await readFile(config.path, 'utf-8')
+    return buildPolicy(content, config.rules)
+  }
+
+  function watchFile(cb: (policy: PolicyDefinition<S, R>) => void): void {
+    // Debounce: many editors write files in multiple events for a single save.
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined
+
+    watch(config.path, () => {
+      clearTimeout(debounceTimer)
+      debounceTimer = setTimeout(async () => {
+        try {
+          const policy = await load()
+          cb(policy)
+        } catch {
+          // Swallow parse errors during watch — the file may be mid-write.
+          // The next fs event (when the write completes) will retry.
+        }
+      }, 50)
+    })
+  }
+
+  return { load, watch: watchFile }
+}