# Mementom integration across backend languages

Start with the [three cumulative integration recipes](/developers/guides/integration-tiers.md): Tier 1
connects sessions and permitted insights; Tier 2 adds rights and challenges; Tier 3
adds account-specific sign-in. Use one consolidated server SDK and the shared
browser controller. Complete framework adapters are planned; the current SDK
helpers and reference examples are described separately in that guide.

Mementom's integration contract is HTTPS and JSON. JavaScript, Python, C#/.NET,
Java, PHP and Go backends call the same endpoints with the same authorization
rules. A `.mjs` file is the Node implementation, not a server requirement.

## Available implementations

| Component | Available coverage |
| --- | --- |
| [JavaScript server SDK](/developers/downloads/mementom-sdk.mjs) | Setup/configuration, authentication, protected-decision verification and consumption, company API, session insights, optional cookies and separately authenticated Marketing API |
| [Shared browser controller](/developers/downloads/mementom-browser.mjs) | Opening, focus, cancellation, timeout and opaque completion; works with every backend language |
| [Python HTTP reference](/developers/downloads/mementom_http.py) | Python 3.10+ standard-library HTTP transport, configuration retrieval, catalog/validation and current-session insight read/write; no Node dependency |
| .NET, Java, PHP and Go | Direct HTTPS integration using the contracts below; native SDKs have not been shipped |

The Python reference is not a full authentication SDK. It does not verify encrypted
decisions, manage callback state or create session cookies. Generated OpenAPI clients
also need these application and cryptographic layers before accepting protected
actions. Do not treat a successful HTTP request or popup message as authorization.

## One API contract

Use the [company OpenAPI specification](/developers/mementom-openapi.json) for
request fields, response schemas and operation IDs, and the separate
[Marketing specification](/developers/mementom-marketing-openapi.json) for its
credential and permissions. There is no public npm, PyPI, NuGet or Maven release.
Pin downloaded reference sources in your own server repository.

| Surface | Production origin | Authority |
| --- | --- | --- |
| Authentication, setup and company API | `https://auth.mementom.app` | Company server credential; app ownership and endpoint-specific rights |
| Company insight API | `https://mementom.app` | Company credential, current app session and holder's separate sharing permission |
| Marketing API | `https://mementom.app` | Separately issued scoped Marketing API credential |
| Authorization window | Service-issued authorization URL | Only the Mementom-owned surface handles private credentials |

Send `Authorization: Bearer <server credential>`, `Content-Type: application/json`
for JSON bodies and `Accept: application/json`. Follow the OpenAPI path-level
server override for insights. Do not forward browser Origin, cookie or Sec-Fetch
headers to server integrations. Configure trusted service origins on the server;
do not accept them from a browser request. Disable redirects and set a finite
timeout. Never automatically retry an uncertain write or one-use code exchange.

Errors retain the HTTP status and the JSON `error` code; insight errors may also
contain `activityId`, and company SDK diagnostics use `x-mementom-request-id`.
Do not log credentials, session IDs, callback codes or raw response bodies.

## Authentication and browser contract

1. Register the app's public RSA JWK with explicit `/api/v1/integration-setup`.
   Keep the private key on the company server. Ordinary startup never repeats a
   mutating setup operation.
2. Read `/api/v1/applications/{applicationId}/integration-config`. Check the app
   and company, public-key match, allowed algorithms, callbacks and active
   challenge bindings. Cache no longer than the returned limit or 60 seconds.
   A failed refresh must not authorize a new attempt with stale configuration.
3. Create a connection request using the saved login action and random state.
   Retain the original state, request, callback and configuration bindings for
   that attempt. Give the browser only the service-issued URL and public request
   ID required by the [window controller](/developers/guides/browser-window.md).
4. The backend validates the bound callback and exchanges the one-use code using
   the original app and response destination. Check the returned request ID.
   Store only the fresh opaque session in your framework's protected cookie or
   session transport. A challenge that is off does not establish identity.
5. Use that same session for live rights and insight operations. Mementom resolves
   the keyring internally. Do not create a persistent keyring alias or cache an
   approval as an alternative to live authorization. Sign-out revokes the session.

The browser module is ordinary JavaScript even when your backend is Python, .NET,
Java, PHP or Go. It sends only the public request ID and opaque status through the
approved return channel. Private phrases, images, proofs, company credentials and
sessions never enter a company page or its browser controller.

## Current-session insights in Python

Download `mementom_http.py` to your server project and use it after your backend
has completed a bound login. No keyring ID is accepted or needed.

```python
import os
from mementom_http import MementomHTTP

mementom = MementomHTTP(application_id, os.environ["MEMENTOM_VENDOR_CREDENTIAL"])
catalog = mementom.catalog()
session = mementom.for_session(current_session_id)  # From protected server transport.
result = session.ingest(
    expected_revision=catalog["revision"],
    dataset_id=registered_dataset_id,
    event_id=stored_event_id,
    sample={"schemaVersion": 1, "observedAt": stored_observation_time,
            "values": trusted_business_values},
)
permitted_values = session.read()
```

Use an approved, non-sample, company-asserted dataset and obtain holder permission.
Validation writes no holder records and does not grant permission. Keep the same
event ID, timestamp and values if reconciling/retrying an ingestion. Reads include
only this app's permitted, unexpired values. Withdrawn permission, expired sessions
and changes to the sharing scope take effect at the service.

## Protected-decision verification profile

Full native adapters must implement and test these requirements before accepting
a protected action. Use maintained cryptographic libraries for each language.

* Decode base64url without padding. The encrypted JSON envelope uses `protected`,
  `encryptedKey`, `iv`, `ciphertext` and `tag` fields. Its decoded protected header
  must specify `alg=RSA-OAEP-256`, `enc=A256GCM`,
  `typ=mementom-decision+jwe`, and the registered response key ID/version.
* Decrypt the 32-byte content key with RSA-OAEP using SHA-256, MGF1-SHA-256 and an
  empty label. Decrypt AES-256-GCM using the encoded `protected` string's UTF-8
  bytes as associated data. Authenticate the tag before reading plaintext.
* The plaintext is signed JSON containing `protected`, `payload` and `signature`.
  Require `alg=EdDSA` and `typ=mementom-signed-payload-v1`. Verify Ed25519 over
  the exact ASCII `protected.payload` using the trusted configuration signing key.
  Never reserialize either signed component or accept a key supplied by the result.
* Require `version=mementom-gate-proof-v1`, an unexpired Unix-seconds deadline,
  and response-key ID/version matching the outer header. Check the original
  vendor, application, audience, challenge, gate request, state, action, resource,
  visible-details and network-policy bindings required for that operation.
* Require `sessionContract=mementom-session-only-v1`. Calculate
  `sessionHash = base64url(SHA256(UTF8(sessionId)))`, then
  `accountSessionBinding = base64url(SHA256(UTF8("session-binding\0" + sessionHash)))`.
  The separator is one zero byte, not the two literal characters backslash and 0.
* Require the result ID and nonce, then consume the verified decision through the
  API before applying the protected action. Enforce one-use processing in the
  company application. A valid signature alone does not grant the action.

Webhook signatures are a separate HMAC-SHA-256 contract over the timestamp, a
literal dot and the exact raw body bytes. Verify the timestamp window and compare
the `v1=` base64url signature in constant time before parsing.

## Adapter acceptance

A full language SDK must pass the same cases: configuration/key mismatch and
rotation; original callback bindings across refresh; invalid signature, tampered
ciphertext, wrong session/app and expiry; one-use replay; denied/withdrawn insight
permission and cross-app isolation; timeout/redirect rejection; safe diagnostics;
and the shared window controller's cancellation, origin and source checks.
HTTP client generation alone does not meet these requirements.