forgelib 1.1.0

The standard library for agent-built SaaS: hardened infra primitives on Postgres
Documentation
{
  "primitive": "auth",
  "scenarios": [
    {
      "name": "password_hash_verify_and_upgrade_signal",
      "steps": [
        { "op": "auth.hash_password", "args": { "plain": "correct horse battery staple" }, "as": "hash", "expect": { "shape": { "$type": "string" } } },
        { "op": "auth.verify_password", "args": { "plain": "correct horse battery staple", "hash": { "$ref": "hash" } }, "expect": { "value": true } },
        { "op": "auth.needs_rehash", "args": { "hash": { "$ref": "hash" } }, "expect": { "value": false } },
        { "op": "auth.needs_rehash", "args": { "hash": "malformed" }, "expect": { "value": true } },
        { "op": "auth.verify_password", "args": { "plain": "x", "hash": "malformed" }, "expect": { "error": "Invalid" } }
      ]
    },
    {
      "name": "session_create_validate_revoke",
      "steps": [
        { "op": "auth.create_session", "args": { "user_id": "u1" }, "as": "t" },
        { "op": "auth.validate_session", "args": { "token": { "$ref": "t" } }, "expect": { "value": "u1" } },
        { "op": "auth.revoke_session", "args": { "token": { "$ref": "t" } } },
        { "op": "auth.validate_session", "args": { "token": { "$ref": "t" } }, "expect": { "value": null } }
      ]
    },
    {
      "name": "api_key_create_then_verify",
      "steps": [
        { "op": "auth.create_api_key", "args": { "owner_id": "o1", "label": "ci" }, "as": "k",
          "expect": { "shape": { "id": { "$type": "string" }, "secret": { "$type": "string" } } } },
        { "op": "auth.verify_api_key", "args": { "key": { "$ref": "k.secret" } }, "expect": { "shape": { "owner_id": "o1", "label": "ci" } } }
      ]
    },
    {
      "name": "api_key_returns_metadata",
      "note": "create_api_key returns the non-secret id, one-time secret, caller label, and creation timestamp consistently across bindings.",
      "steps": [
        { "op": "auth.create_api_key", "args": { "owner_id": "o1", "label": "billing", "expires_in_seconds": 900, "scopes": ["invoice:read"], "metadata": { "team": "finance" } }, "as": "k",
          "expect": { "shape": { "id": { "$type": "string" }, "secret": { "$type": "string" }, "label": "billing", "created_at_ms": { "$type": "number" }, "expires_at_ms": { "$type": "number" }, "scopes": ["invoice:read"], "metadata": { "team": "finance" } } } },
        { "op": "auth.verify_api_key", "args": { "key": { "$ref": "k.secret" } },
          "expect": { "shape": { "owner_id": "o1", "label": "billing", "expires_at_ms": { "$type": "number" }, "scopes": ["invoice:read"], "metadata": { "team": "finance" } } } }
      ]
    },
    {
      "name": "one_time_token_single_use",
      "note": "A token is consumed exactly once, and only with the purpose it was minted for; a wrong purpose leaves it intact.",
      "steps": [
        { "op": "auth.create_token", "args": { "user_id": "u1", "purpose": "password-reset", "ttl_seconds": 900, "payload": "return-to=/settings" }, "as": "t" },
        { "op": "auth.consume_token", "args": { "token": { "$ref": "t" }, "purpose": "email-verify" }, "expect": { "value": null } },
        { "op": "auth.consume_token", "args": { "token": { "$ref": "t" }, "purpose": "password-reset" }, "expect": { "value": { "user_id": "u1", "payload": "return-to=/settings" } } },
        { "op": "auth.consume_token", "args": { "token": { "$ref": "t" }, "purpose": "password-reset" }, "expect": { "value": null } },
        { "op": "auth.consume_token", "args": { "token": "unknown-token", "purpose": "password-reset" }, "expect": { "value": null } }
      ]
    },
    {
      "name": "one_time_token_rejects_bad_input",
      "steps": [
        { "op": "auth.create_token", "args": { "user_id": "u1", "purpose": "", "ttl_seconds": 900 }, "expect": { "error": "Invalid" } },
        { "op": "auth.create_token", "args": { "user_id": "u1", "purpose": "password-reset", "ttl_seconds": 0 }, "expect": { "error": "Invalid" } }
      ]
    },
    {
      "name": "one_time_token_namespace_isolation",
      "note": "Tokens are scoped by Forge namespace like sessions and API keys.",
      "steps": [
        { "op": "auth.create_token", "args": { "user_id": "u1", "purpose": "magic-link", "ttl_seconds": 900 }, "namespace": "app-a", "as": "t" },
        { "op": "auth.consume_token", "args": { "token": { "$ref": "t" }, "purpose": "magic-link" }, "namespace": "app-b", "expect": { "value": null } },
        { "op": "auth.consume_token", "args": { "token": { "$ref": "t" }, "purpose": "magic-link" }, "namespace": "app-a", "expect": { "value": { "user_id": "u1", "payload": "" } } }
      ]
    },
    {
      "name": "session_namespace_isolation",
      "note": "Sessions are scoped by Forge namespace, so two apps can share one database without accepting each other's tokens.",
      "steps": [
        { "op": "auth.create_session", "args": { "user_id": "u1" }, "namespace": "app-a", "as": "t" },
        { "op": "auth.validate_session", "args": { "token": { "$ref": "t" } }, "namespace": "app-a", "expect": { "value": "u1" } },
        { "op": "auth.validate_session", "args": { "token": { "$ref": "t" } }, "namespace": "app-b", "expect": { "value": null } }
      ]
    }
  ]
}