Saltar al contenido principal
Menú para desarrolladores
Vista previa para sociosv0

Firmar solicitudes

Cada solicitud que la plataforma envía a su modelo se firma con la clave Ed25519 de la plataforma, y cada callback que usted devuelve se firma con la suya. Nadie comparte un secreto.

El esquema de firma

El encabezado es ShockAI-Signature: t=timestamp,kid=key id,ed25519=signature. La marca de tiempo (timestamp) va en segundos Unix, y el id de la clave (key id) es la huella digital RFC 7638 de la clave de firma. La firma (signature) es Ed25519, en base64url sin relleno, sobre seis líneas unidas por un salto de línea: shockai-model-api-v0, la marca de tiempo, el método, la URL de destino, la Idempotency-Key (una línea vacía cuando no hay) y el SHA-256 en hexadecimal del cuerpo sin procesar.

La URL de destino es el origen en minúsculas sin el puerto predeterminado, seguido de la ruta y la consulta exactamente como se enviaron. Vincula una solicitud a su host y un callback a su ejecución, y la marca de tiempo la vincula a un momento: rechace cualquier marca de tiempo que difiera más de 300 segundos de su reloj.

Claves

Las claves públicas de la plataforma son JWK en /developers/keys/v0.json. Cárguelas al iniciar, use aquella cuya huella digital sea el kid del encabezado, y vuelva a obtener el archivo cuando una solicitud nombre una clave que usted no tiene.

Su manifiesto declara sus propias claves públicas en signing.callbackKeys, y la plataforma las fija cuando su modelo se conecta. Mantenga la mitad privada en su host; la plataforma nunca la pide. Las plantillas imprimen en su primer arranque el bloque que hay que fijar, y se niegan a arrancar si se pierde su archivo de clave, en lugar de crear una clave nueva bajo la misma versión.

Verificar

Verifique contra los bytes del cuerpo sin procesar, exactamente como se recibieron, antes de analizarlo. Volver a serializar el JSON cambia los bytes y rompe la firma. El verificador de Python necesita el paquete cryptography.

import { createHash, createPublicKey, verify } from 'node:crypto';

export type Ed25519Jwk = { kty: 'OKP'; crv: 'Ed25519'; x: string };

/** 'unknown_key': fetch the platform's keys again, then check once more. */
export type SignatureCheck = 'ok' | 'malformed' | 'expired' | 'unknown_key' | 'mismatch';

/** The key id in the header: the key's RFC 7638 thumbprint. */
function thumbprint(jwk: Ed25519Jwk): string {
  const members = JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x });
  return createHash('sha256').update(members).digest('base64url');
}

/**
 * Checks a ShockAI-Signature header. `target` is your public origin and the
 * request-target exactly as received, e.g. https://models.example.com/shockai/v0/runs.
 * `keys` are the platform's, from https://app.shockai.co/developers/keys/v0.json
 * (two during a rotation).
 */
export function verifyShockaiSignature(
  header: string | null,
  request: { method: string; target: string; idempotencyKey: string | null; body: string | Buffer },
  keys: Ed25519Jwk[],
  toleranceSeconds = 300,
  nowSeconds = Math.floor(Date.now() / 1000),
): SignatureCheck {
  const parts = (header ?? '').split(',').map((part) => part.trim());
  const field = (name: string) => {
    const values = parts.filter((part) => part.startsWith(`${name}=`)).map((part) => part.slice(name.length + 1));
    return values.length === 1 ? values[0]! : '';
  };
  const [timestamp, kid, signature] = [field('t'), field('kid'), field('ed25519')];

  if (!/^[0-9]{1,12}$/.test(timestamp) || !/^[A-Za-z0-9_-]{86}$/.test(signature)) return 'malformed';
  if (Math.abs(nowSeconds - Number(timestamp)) > toleranceSeconds) return 'expired';

  const jwk = keys.find((key) => thumbprint(key) === kid);
  if (!jwk) return 'unknown_key';

  const base = [
    'shockai-model-api-v0',
    timestamp,
    request.method.toUpperCase(),
    request.target,
    request.idempotencyKey ?? '',
    createHash('sha256').update(request.body).digest('hex'),
  ].join('\n');

  const valid = verify(
    null,
    Buffer.from(base),
    createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, format: 'jwk' }),
    Buffer.from(signature, 'base64url'),
  );
  return valid ? 'ok' : 'mismatch';
}

Rotar una clave

La plataforma publica su próxima clave junto a la actual antes de cambiar, así que confíe en todas las claves del archivo. Para rotar la suya, cree la clave nueva, publique una versión del manifiesto que liste ambas claves y vuelva a conectar, firme con la clave nueva (una plantilla la lee de HOST_SIGNING_KEY o de data/host-key.pem) y luego retire la antigua en la versión siguiente.

Vector de prueba

La clave es la TEST 1 de la RFC 8032, cuya mitad privada es pública. Compruebe primero su Ed25519 contra la RFC, y luego su cadena firmada y su encabezado contra estos valores. Nunca firme nada real con esta clave.

Clave privada (RFC 8032 TEST 1)
9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60
Clave pública (JWK)
{"kty":"OKP","crv":"Ed25519","x":"11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"}
Id de la clave
kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k
Marca de tiempo
1790000000
Método
POST
URL de destino
https://models.example.com/shockai/v0/runs
Idempotency-Key
run_7c4f2a
Cuerpo
{"specVersion":"0.1"}
Cadena firmada
shockai-model-api-v0 1790000000 POST https://models.example.com/shockai/v0/runs run_7c4f2a 1700d07dca59ed2974e6c9aa0a00833336008879d076b51e9a28f984f7a30b79
Encabezado esperado
t=1790000000,kid=kPrK_qmxVWaYVA9wwBF6Iuo3vVzz7TxHCTwXBygrS4k,ed25519=icmmz4Se1SDqakdLPEA9iLxwTTtteH-fL6IL7msudlV3l-hU6cZ5TrpR0CzuLOBHZhSw9jTt1Wvdko17Gz0fCw
shell
# Recompute the test vector's signature with OpenSSL 3
cat > rfc8032-test1.pem <<'PEM'
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIJ1hsZ3v/VpguoRK9JLsLMREScVpezJpGXA7rAMcrn9g
-----END PRIVATE KEY-----
PEM
body_hash=$(printf '%s' '{"specVersion":"0.1"}' | openssl dgst -sha256 -r | cut -d' ' -f1)
printf '%s\n' 'shockai-model-api-v0' '1790000000' 'POST' 'https://models.example.com/shockai/v0/runs' 'run_7c4f2a' > base.txt
printf '%s' "$body_hash" >> base.txt
openssl pkeyutl -sign -rawin -inkey rfc8032-test1.pem -in base.txt \
  | openssl base64 -A | tr '+/' '-_' | tr -d '='
# → icmmz4Se1SDqakdLPEA9iLxwTTtteH-fL6IL7msudlV3l-hU6cZ5TrpR0CzuLOBHZhSw9jTt1Wvdko17Gz0fCw