Initial Commit

packages/api-stack/api/api-auth/src/csrf-policy/csrf-policy.ts

@@ -0,0 +1,28 @@
+import type { OpenApiSecurityScheme } from "../security-scheme/security-scheme.js";
+
+/**
+ * Default CSRF policy keyed off an `OpenApiSecurityScheme`.
+ *
+ * Per design doc §6: "Cookie-based auth adapters trigger CSRF verification."
+ * The default is ON for any scheme that ambient-authority sends with the
+ * request (cookies); OFF for any scheme that requires the caller to actively
+ * attach the credential to the request (bearer tokens, OAuth2 access tokens,
+ * OIDC).
+ *
+ * The host applies per-route overrides on top of this default. This module
+ * exposes only the policy default; the host owns the override path.
+ */
+export const CsrfPolicy = Object.freeze({
+    /**
+     * Returns `true` when requests authenticated via the supplied scheme MUST
+     * carry a CSRF token (double-submit, header-pin, or origin check — the
+     * host picks the mechanism). Returns `false` when CSRF verification is
+     * not required by default.
+     */
+    requiresCsrf(scheme: OpenApiSecurityScheme): boolean {
+        if (scheme.type === "apiKey" && scheme.in === "cookie") {
+            return true;
+        }
+        return false;
+    },
+});