@autra-io/react-native-card 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `AutraCardForm`: hosted-WebView card tokenization component. Loads only a
+  backend-created `hostedCardUrl` (hosted card session); no provider token
+  ever reaches the app. Strict postMessage schema with origin allow-list and
+  field allow-list on `tokenized` payloads.
+- WebView hardening: HTTPS-only hosted URL, full navigation allow-list in
+  `onShouldStartLoadWithRequest` with wildcard `originWhitelist` (blocked
+  navigations never escape to the OS browser), `incognito` +
+  `cacheEnabled: false` (no disk persistence of the hosted page),
+  `mixedContentMode: 'never'`, `allowFileAccess: false`.
+- Terminal guard: after a successful `tokenized` message, duplicate messages
+  and stray errors are ignored (no double `onSuccess`).
+- `onHttpError` document-vs-sub-resource discrimination: sub-resource
+  failures (favicon/assets/page fetches) no longer abort the flow.
+- `allowedOrigins` normalization: trailing slashes are canonicalized and
+  non-HTTPS entries dropped; an empty normalized list is a
+  `configuration_error`.
+- Configuration errors are emitted from an effect (never during render).
+- Functional mock-API React Native app test harness
+  (`test/functional-app/`).
+- Public exports in `src/index.ts`
+  (`AutraCardForm`, `AUTRA_REACT_NATIVE_CARD_SDK_VERSION`,
+  `AutraCardTokenizedResult`, `AutraCardError`).
+- Repository foundation: package scaffold (`package.json`, `tsconfig`, tsup,
+  Vitest, ESLint flat config, Prettier).
+- CI workflow (Node 20 & 22) and package-smoke job.
+- Security workflow: `npm audit` (gate), gitleaks (gate), semgrep (advisory).
+- Dependabot (npm + github-actions), CODEOWNERS, PR template.
+- Pre-commit configuration (pre-commit framework).
+- GitHub Copilot review instructions.
+- Integration documentation (`docs/platform.md`, `docs/integration/*`).
+- Secret-safety: `.gitignore`/`.env.example` guardrails and package smoke test.
+
+### Changed
+
+- Package prepared for public release: MIT license, `publishConfig.access:
+public`; publishing remains manual and gated (see `docs/platform.md`).
+
+### Notes
+
+- No version has been published to npm yet; the entries above will ship as
+  `0.1.0`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,298 @@
+# @autra-io/react-native-card
+
+React Native SDK for secure card tokenization via Autra's hosted card page.
+**Card data never touches your app or your servers.**
+
+[![CI](https://github.com/autratech/autra-card-sdk-react-native/actions/workflows/ci.yml/badge.svg)](https://github.com/autratech/autra-card-sdk-react-native/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+<!-- Enable after the first npm publish:
+[![npm version](https://img.shields.io/npm/v/%40autra-io%2Freact-native-card.svg)](https://www.npmjs.com/package/@autra-io/react-native-card)
+-->
+
+> 🇧🇷 [Leia este README em português](./README.pt-BR.md) · Guias completos em
+> português no portal do desenvolvedor <!-- PLACEHOLDER: developer portal URL -->
+
+## Table of contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [How it works](#how-it-works)
+- [Quickstart](#quickstart)
+- [API reference](#api-reference)
+- [Security & PCI](#security--pci)
+- [Testing your integration](#testing-your-integration)
+- [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [Support](#support)
+- [License](#license)
+
+## Features
+
+- **Hosted-page tokenization** — the cardholder types PAN/CVV on an
+  Autra-hosted page rendered inside a WebView. Card data never transits your
+  app or your backend, which helps reduce your PCI DSS scope.
+- **Hardened WebView out of the box** — HTTPS-only, full navigation
+  allow-list (blocked navigations never escape to the OS browser),
+  `mixedContentMode: 'never'`, incognito mode, no disk cache, no file access.
+- **Strict message bridge** — origin allow-list and schema validation on every
+  message from the hosted page; a terminal guard makes `onSuccess` fire at
+  most once.
+- **Typed end to end** — `AutraCardFormProps`, `AutraCardTokenizedResult` and
+  a normalized `AutraCardError` taxonomy, all in TypeScript.
+- **Zero runtime dependencies** — the SDK adds nothing to your bundle beyond
+  its own component; `react-native-webview` is a peer dependency you control.
+
+## Requirements
+
+| Dependency             | Version   |
+| ---------------------- | --------- |
+| React                  | >= 18.0.0 |
+| React Native           | >= 0.72.0 |
+| `react-native-webview` | >= 13.0.0 |
+
+- `react-native-webview` is a **required peer dependency** — install it in
+  your app (see below); the SDK does not bundle it.
+- **Expo**: works with development builds / `expo prebuild` (because
+  `react-native-webview` contains native code). Expo Go is not supported.
+  <!-- PLACEHOLDER: confirm official Expo support statement with the team -->
+- **New Architecture**: the SDK itself has no native code; support follows
+  your installed `react-native-webview` version.
+  <!-- PLACEHOLDER: confirm New Architecture statement with the team -->
+- Node.js >= 20 is only required to develop this repository, not to use the
+  SDK.
+
+## Installation
+
+```bash
+npm install @autra-io/react-native-card react-native-webview
+# or
+yarn add @autra-io/react-native-card react-native-webview
+```
+
+iOS (bare React Native):
+
+```bash
+cd ios && pod install
+```
+
+Expo:
+
+```bash
+npx expo install react-native-webview
+npm install @autra-io/react-native-card
+```
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant App as Your app (SDK)
+    participant Backend as Your backend
+    participant Autra as Autra Platform API
+    participant Page as Autra hosted card page
+
+    App->>Backend: request a card session
+    Backend->>Autra: POST /v1/acquiring/card-sessions (service credentials)
+    Autra-->>Backend: hostedCardUrl (short-lived, single-use)
+    Backend-->>App: hostedCardUrl
+    App->>Page: <AutraCardForm hostedCardUrl /> loads the page in a WebView
+    Note over Page: Cardholder types PAN/CVV here —<br/>never in your app
+    Page->>Autra: tokenize (direct, over HTTPS)
+    Autra-->>Page: opaque token references
+    Page-->>App: postMessage: tokenized
+    App->>Backend: slugStoredCard (opaque) for future charges
+```
+
+Card data flows only between the cardholder and Autra's hosted page — it never
+transits your app or backend. Your systems only ever see two opaque values:
+the short-lived `hostedCardUrl` going in, and the `slugStoredCard` /
+`slugToken` references coming out.
+
+## Quickstart
+
+### Step 1 — Backend: create a hosted card session
+
+Card sessions are created **server-side** with your Autra service credentials.
+Never call this from the app, and never embed credentials in the app.
+
+```ts
+// Your backend (Node example). Sandbox base URL: https://api.sandbox.autra.io
+// Production: see the developer portal. <!-- PLACEHOLDER: production URL -->
+app.post('/card-sessions', async (_req, res) => {
+  const response = await fetch('https://api.sandbox.autra.io/v1/acquiring/card-sessions', {
+    method: 'POST',
+    headers: {/* your Autra service credentials — server-side only */},
+  });
+  const { hostedCardUrl } = await response.json();
+  // hostedCardUrl is short-lived and single-use — mint one per attempt.
+  res.json({ hostedCardUrl });
+});
+```
+
+### Step 2 — App: render the form
+
+```tsx
+import { useState } from 'react';
+import { Button, View } from 'react-native';
+import {
+  AutraCardForm,
+  type AutraCardTokenizedResult,
+  type AutraCardError,
+} from '@autra-io/react-native-card';
+
+export function AddCardScreen() {
+  const [hostedCardUrl, setHostedCardUrl] = useState<string | null>(null);
+
+  async function startCardEntry() {
+    // Ask YOUR backend for a fresh session (Step 1). URLs are single-use:
+    // request a new one for every attempt — never hardcode or reuse them.
+    const response = await fetch('https://your-backend.example.com/card-sessions', {
+      method: 'POST',
+    });
+    const body = (await response.json()) as { hostedCardUrl: string };
+    setHostedCardUrl(body.hostedCardUrl);
+  }
+
+  if (!hostedCardUrl) {
+    return <Button title="Add card" onPress={startCardEntry} />;
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <AutraCardForm
+        hostedCardUrl={hostedCardUrl}
+        onReady={() => {
+          // Hosted page is interactive — hide your loading indicator.
+        }}
+        onSuccess={(result: AutraCardTokenizedResult) => {
+          // Send result.slugStoredCard to your backend and store it there.
+          // Your backend uses it later to charge the card — the app is done.
+        }}
+        onError={(error: AutraCardError) => {
+          if (error.code === 'token_expired' || error.retryable) {
+            // Sessions are short-lived: create a NEW session and retry.
+            setHostedCardUrl(null);
+            return;
+          }
+          // Non-retryable: surface a friendly message and report error.code.
+        }}
+        style={{ flex: 1 }}
+      />
+    </View>
+  );
+}
+```
+
+## API reference
+
+### `<AutraCardForm />`
+
+| Prop             | Type                                         | Required | Description                                                                                   |
+| ---------------- | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
+| `hostedCardUrl`  | `string`                                     | yes      | Short-lived hosted card session URL created by your backend. Must be HTTPS.                   |
+| `onSuccess`      | `(result: AutraCardTokenizedResult) => void` | yes      | Fires **at most once**, on successful tokenization. Later messages are ignored.               |
+| `onError`        | `(error: AutraCardError) => void`            | yes      | Fires on configuration, session, navigation or tokenization errors.                           |
+| `onReady`        | `(requestId?: string) => void`               | no       | Hosted page validated the session and is interactive.                                         |
+| `allowedOrigins` | `readonly string[]`                          | no       | HTTPS origins allowed for navigation and messages. Defaults to the origin of `hostedCardUrl`. |
+| `style`          | `StyleProp<ViewStyle>`                       | no       | Style for the underlying WebView.                                                             |
+| `testID`         | `string`                                     | no       | Test identifier forwarded to the WebView.                                                     |
+
+### `AutraCardTokenizedResult`
+
+All fields are **opaque references** — the SDK never exposes card data.
+
+| Field                 | Type      | Description                                                  |
+| --------------------- | --------- | ------------------------------------------------------------ |
+| `slugStoredCard`      | `string?` | Reference your backend uses to charge the stored card later. |
+| `slugToken`           | `string?` | Single-purpose token reference.                              |
+| `tokenExpirationDate` | `string?` | Expiration of the token reference.                           |
+| `brand`               | `string?` | Card brand (display only).                                   |
+| `last4`               | `string?` | Last four digits (display only).                             |
+| `expirationMonth`     | `string?` | Card expiration month (display only).                        |
+| `expirationYear`      | `string?` | Card expiration year (display only).                         |
+| `requestId`           | `string?` | Correlation id for support requests.                         |
+
+At least one of `slugStoredCard` / `slugToken` is always present on success.
+
+### `AutraCardError`
+
+`{ code, message, requestId?, retryable? }`. Handle by `code`; when
+`retryable` is `true`, create a **new** session and retry.
+
+| Code                      | Meaning                                                       | What to do                                      |
+| ------------------------- | ------------------------------------------------------------- | ----------------------------------------------- |
+| `configuration_error`     | Invalid/non-HTTPS `hostedCardUrl`, or empty `allowedOrigins`. | Fix the integration — not user-recoverable.     |
+| `token_expired`           | Session expired or unauthorized (sessions are short-lived).   | Create a new session and reload the form.       |
+| `message_origin_rejected` | Message or navigation from an origin outside the allow-list.  | Investigate; do not weaken `allowedOrigins`.    |
+| `message_invalid`         | Malformed message from the hosted page.                       | Retry with a new session; report `requestId`.   |
+| `validation_error`        | Cardholder input rejected.                                    | The hosted page guides the user; no app action. |
+| `tokenization_failed`     | Page failed to load or tokenization failed upstream.          | If `retryable`, retry with a new session.       |
+
+### `AUTRA_REACT_NATIVE_CARD_SDK_VERSION`
+
+Version marker string, useful for support tickets and smoke tests.
+
+## Security & PCI
+
+- Card data (PAN, CVV, cardholder data) is entered **only** on the
+  Autra-hosted page and sent directly to Autra — it never transits your app or
+  backend, which helps reduce your PCI DSS scope.
+- Your app only handles the opaque, short-lived `hostedCardUrl` (in) and the
+  opaque `slugStoredCard` / `slugToken` references (out).
+- Keep service credentials (`clientSecret`, strong access tokens) **server-side
+  only** — never embed them in the app.
+- Never log PAN/CVV/cardholder data, and never log the `hostedCardUrl`. Use
+  `requestId` for correlation.
+- The WebView is hardened by default: HTTPS-only, navigation allow-list,
+  no mixed content, incognito, no disk cache, no file access.
+
+Found a vulnerability? See [SECURITY.md](./SECURITY.md) — please do not open a
+public issue.
+
+## Testing your integration
+
+- Use the **sandbox** environment (`https://api.sandbox.autra.io`) with mock
+  values only — never real card data.
+  <!-- PLACEHOLDER: sandbox test card numbers, if provided by the team -->
+- For unit tests, inject your session-creation function and mock the WebView
+  bridge — see
+  [`test/functional-app/`](./test/functional-app/FunctionalAutraCardApp.ts)
+  for a complete reference harness driving `ready`, `tokenized` and `error`
+  flows with a mocked backend.
+
+## Troubleshooting
+
+- **Blank WebView** — `react-native-webview` is not installed/linked. Install
+  it (see [Installation](#installation)) and run `pod install` on iOS.
+- **`configuration_error` immediately** — the `hostedCardUrl` is malformed or
+  not HTTPS, or your custom `allowedOrigins` normalized to an empty list.
+- **`token_expired`** — hosted sessions are short-lived and single-use. Create
+  a session right before rendering the form, one per attempt.
+- **Nothing happens after submit** — check that you are not filtering the
+  hosted page's origin out via a custom `allowedOrigins`.
+- **Cleartext/HTTP hosted URL** — not supported by design; the SDK rejects
+  non-HTTPS URLs.
+
+## Documentation
+
+- Integration guides: developer portal
+  <!-- PLACEHOLDER: developer portal URL (EN + PT-BR) -->
+- [Backend flow overview](./docs/integration/backend-flow.md)
+- [SDK scope and limitations](./docs/integration/limitations.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Never include real card data or
+secrets in issues, PRs or examples.
+
+## Support
+
+- Bugs and feature requests:
+  [GitHub issues](https://github.com/autratech/autra-card-sdk-react-native/issues)
+- Integration support: <!-- PLACEHOLDER: support channel/email -->
+
+## License
+
+[MIT](./LICENSE)

package/README.pt-BR.md

@@ -0,0 +1,133 @@
+<!--
+  Este arquivo espelha apenas o essencial (features, instalação, quickstart,
+  erros) do README.md. Ao alterar o quickstart ou a API no README.md,
+  atualize este arquivo também. A documentação completa vive no README.md.
+-->
+
+# @autra-io/react-native-card
+
+SDK React Native para tokenização segura de cartões via página hospedada da
+Autra. **Os dados do cartão nunca passam pelo seu app nem pelos seus
+servidores.**
+
+> 🌎 [Read this README in English](./README.md) (documentação completa) ·
+> Guias completos no portal do desenvolvedor
+> <!-- PLACEHOLDER: URL do portal do desenvolvedor -->
+
+## Por que usar
+
+- **Tokenização em página hospedada** — o portador digita PAN/CVV em uma
+  página hospedada pela Autra, dentro de uma WebView. Os dados do cartão nunca
+  transitam pelo seu app ou backend, o que ajuda a reduzir seu escopo PCI DSS.
+- **WebView endurecida por padrão** — HTTPS-only, allow-list de navegação,
+  sem conteúdo misto, incognito, sem cache em disco, sem acesso a arquivos.
+- **Bridge de mensagens estrita** — validação de origem e de schema em toda
+  mensagem; `onSuccess` dispara no máximo uma vez.
+- **Tipado de ponta a ponta** e **zero dependências de runtime**.
+
+## Instalação
+
+```bash
+npm install @autra-io/react-native-card react-native-webview
+# iOS (React Native bare): cd ios && pod install
+# Expo: npx expo install react-native-webview
+```
+
+Requisitos: React >= 18, React Native >= 0.72, `react-native-webview` >= 13
+(peer dependency obrigatória). Expo: requer development build / `expo
+prebuild` (Expo Go não é suportado).
+
+## Início rápido
+
+### Passo 1 — Backend: criar uma sessão de cartão hospedada
+
+As sessões são criadas **no servidor**, com suas credenciais de serviço Autra.
+Nunca chame esta API do app e nunca embuta credenciais no app.
+
+```ts
+// Seu backend (exemplo Node). Sandbox: https://api.sandbox.autra.io
+// Produção: consulte o portal do desenvolvedor. <!-- PLACEHOLDER: URL produção -->
+app.post('/card-sessions', async (_req, res) => {
+  const response = await fetch('https://api.sandbox.autra.io/v1/acquiring/card-sessions', {
+    method: 'POST',
+    headers: {/* credenciais de serviço Autra — somente no servidor */},
+  });
+  const { hostedCardUrl } = await response.json();
+  // hostedCardUrl é de curta duração e uso único — gere uma por tentativa.
+  res.json({ hostedCardUrl });
+});
+```
+
+### Passo 2 — App: renderizar o formulário
+
+```tsx
+import { useState } from 'react';
+import { Button, View } from 'react-native';
+import {
+  AutraCardForm,
+  type AutraCardTokenizedResult,
+  type AutraCardError,
+} from '@autra-io/react-native-card';
+
+export function AdicionarCartaoScreen() {
+  const [hostedCardUrl, setHostedCardUrl] = useState<string | null>(null);
+
+  async function iniciarEntradaDeCartao() {
+    // Peça ao SEU backend uma sessão nova (Passo 1). URLs são de uso único:
+    // solicite uma nova a cada tentativa — nunca fixe ou reutilize.
+    const response = await fetch('https://seu-backend.example.com/card-sessions', {
+      method: 'POST',
+    });
+    const body = (await response.json()) as { hostedCardUrl: string };
+    setHostedCardUrl(body.hostedCardUrl);
+  }
+
+  if (!hostedCardUrl) {
+    return <Button title="Adicionar cartão" onPress={iniciarEntradaDeCartao} />;
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <AutraCardForm
+        hostedCardUrl={hostedCardUrl}
+        onReady={() => {
+          // Página hospedada pronta — esconda seu indicador de carregamento.
+        }}
+        onSuccess={(result: AutraCardTokenizedResult) => {
+          // Envie result.slugStoredCard ao seu backend e armazene lá.
+          // O backend usa essa referência para cobranças futuras.
+        }}
+        onError={(error: AutraCardError) => {
+          if (error.code === 'token_expired' || error.retryable) {
+            // Sessões expiram rápido: crie uma NOVA sessão e tente de novo.
+            setHostedCardUrl(null);
+            return;
+          }
+          // Não recuperável: mostre uma mensagem amigável e reporte error.code.
+        }}
+        style={{ flex: 1 }}
+      />
+    </View>
+  );
+}
+```
+
+## Códigos de erro (`AutraCardError`)
+
+| Código                    | Significado                                                   | O que fazer                                    |
+| ------------------------- | ------------------------------------------------------------- | ---------------------------------------------- |
+| `configuration_error`     | `hostedCardUrl` inválida/não-HTTPS ou `allowedOrigins` vazio. | Corrigir a integração — não é erro do usuário. |
+| `token_expired`           | Sessão expirada ou não autorizada.                            | Criar nova sessão e recarregar o formulário.   |
+| `message_origin_rejected` | Mensagem/navegação de origem fora da allow-list.              | Investigar; não enfraquecer `allowedOrigins`.  |
+| `message_invalid`         | Mensagem malformada da página hospedada.                      | Tentar com nova sessão; reportar `requestId`.  |
+| `validation_error`        | Dados do cartão rejeitados.                                   | A própria página orienta o usuário.            |
+| `tokenization_failed`     | Falha de carregamento ou de tokenização.                      | Se `retryable`, tentar com nova sessão.        |
+
+## Documentação completa
+
+Referência completa da API, segurança & PCI, testes e troubleshooting:
+[README.md (English)](./README.md).
+
+## Licença
+
+[MIT](./LICENSE)

package/SECURITY.md

@@ -0,0 +1,61 @@
+# Security Policy
+
+`@autra-io/react-native-card` is a **payment-adjacent SDK**. Card data and
+credentials demand strict handling. This policy is mandatory for all
+contributors (human and AI).
+
+## Reporting a vulnerability
+
+- **Do not** open a public GitHub issue for security vulnerabilities.
+- Report privately via
+  [GitHub private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
+  on this repository, or by email to `security@autra.io`
+  <!-- PLACEHOLDER: confirm the public security contact email with the team -->.
+- Include: affected version/commit, impact, and reproduction steps using
+  **non-sensitive, mock data only**.
+
+> **Never** paste PAN, CVV, cardholder data, real tokens, secrets or sensitive
+> logs into an issue, PR, comment or vulnerability report.
+
+## Handling card & payment data
+
+- **Never** log or store PAN, CVV, expiry or cardholder data — anywhere
+  (app logs, SDK payloads, tests, fixtures, docs, examples).
+- **Never** use real card data in tests or examples. Use mock/fake values.
+- Logs and errors reference `requestId` / `correlationId` only.
+- The tokenized card is referenced by an opaque `slugStoredCard`.
+
+## Credentials & tokens
+
+- **`clientSecret` (OAuth) never goes to the mobile app.**
+- **A strong `accessToken` never goes to the mobile app.**
+- **No provider token of any kind reaches the app.** The app only ever handles
+  a short-lived, single-use **`hostedCardUrl`** (hosted card session) created
+  by your backend; card entry and tokenization happen inside the hosted page.
+- Never commit secrets, tokens, private keys or credentials.
+- `.env` and `.env.*` are git-ignored; only `.env.example` (placeholders) is
+  committed. Real credentials belong in your secret manager — never in the repo.
+
+## If a secret is exposed
+
+1. **Rotate the secret immediately** (before removing it from history).
+2. Report it through the vulnerability-reporting channel above.
+3. Remove it from the working tree and, if needed, purge from git history.
+4. Verify `gitleaks` passes and confirm no other copies remain.
+
+## Security tooling (must stay active)
+
+- **pre-commit** hooks (`.pre-commit-config.yaml`): hygiene, secret/env guard,
+  gitleaks, prettier, eslint, typecheck, `no-commit-to-branch=main`.
+- **CI security workflow** (`.github/workflows/security.yml`):
+  - `npm audit --omit=dev --audit-level=high` (GATE)
+  - `gitleaks` secret scan (GATE)
+  - `semgrep` SAST (advisory — may become a required gate later)
+
+Do not disable or weaken these controls.
+
+## Supported versions
+
+| Version | Supported                              |
+| ------- | -------------------------------------- |
+| `0.x`   | Latest minor release (pre-1.0 preview) |