Skip to content
Rakomi Docs

Secure defaults

This page is the “configuration recommendations and secure default settings” required by CRA Art. 10 for the JS-family SDKs. It is the one documentation page where concrete implementation specifics (algorithms, host names, header names) appear by design — they are instructions for integrators, not a regulatory claim.

It is a single shared page covering all three JS runtimes, with a per-runtime subsection for the differences that matter. We deliberately keep one page rather than per-package pages: a two-person team cannot keep four near-identical pages from drifting, and the security posture is shared across the family — only token storage genuinely differs by runtime.

Shared posture (all runtimes)

Section titled “Shared posture (all runtimes)”

The SDKs ship secure-by-default. You do not need to opt in to any of the following — they are the defaults, and most cannot be disabled:

  • Token signatures are verified with RS256 (asymmetric). The verification algorithm is fixed by policy and is never read from the token header — a token presenting alg: none, HS256, or any symmetric algorithm is rejected.
  • The signing-key set (JWKS) is fetched only from https://api.rakomi.com/.well-known/jwks.json, the pinned issuer host (ADR-004 §D8). The SDKs do not follow a host supplied inside a token and do not consume the public audit mirror at jwks.rakomi.dev.
  • Issuer and audience are enforced. Verification rejects a token whose iss is not the Rakomi platform issuer (https://rakomi.com) and whose aud does not match your configured audience. Always set your expected audience — do not leave it unconstrained.
  • Expiry and not-before are enforced with no implicit clock skew beyond the small default leeway. Expired tokens are rejected.
  • Transport is HTTPS-only. The SDKs refuse to send credentials over plaintext HTTP.
  • API keys are read from configuration, never hard-coded. Use akm_test_* keys in development and akm_live_* keys only in production; keep live keys out of source control.

Per-runtime subsections

Section titled “Per-runtime subsections”

@rakomi/node and @rakomi/sdk-core run in a trusted server environment.

  • Store the API key in an environment variable (or your platform’s secret manager), never in a committed file and never shipped to a browser. A server-side key grants verification on behalf of your tenant.
  • There is no browser. Do not import the Node SDK into client bundles — it expects a server runtime and secret material that must not leave the server.
  • Verify tokens on every protected request; treat a failed verifyToken() result as unauthenticated (401), and surface only the returned code/message/docs_url — never the raw token or internal error detail.
  • Cache the JWKS in-process (the SDK does this for you); do not refetch per request.

See also

Section titled “See also”