Dichiara un account rubato, abbandonato o spostato

Il proprietario firma un avviso su uno degli account collegati della scheda. Da quel momento ogni ricerca di quell’account si apre con l’avviso, finché un avviso regained non lo chiude.

POST/v1/identities/{n}/alerts

Accesso: Richiesta firmata
Client: Client locale o server

Parametri#

Nome	Posizione	Significato
`n`Obbligatorio	Percorso	Numero permanente positivo della scheda.

Corpo JSON#

Nome	Posizione	Significato
`statement`Obbligatorio	JSON	{platform, since, state, subject, time, to, type: "alert", v: 1}. state è stolen (since una data, AAAA-MM-GG), abandoned, moved (to = {handle, subject}) oppure regained.
`salt`Obbligatorio	JSON	32 byte casuali in 64 caratteri hex minuscoli, scelti dal browser.
`entry`Obbligatorio	JSON	{text, signature}: la voce {c, key, kind, signer, time, token, v: 2} in JSON canonico senza firma, e la firma di "veil-rubrica:card-entry:v2\n" + text con X-Public-Key.

Questa chiamata richiede anche le intestazioni comuni di firma, nonce e timestamp. Prepara e firma request.json prima di usare l’esempio. Firma delle richieste

Esempi di richiesta#

cURL

curl -fsS -X POST \
  -H "X-Public-Key: $PUBLIC_KEY" \
  -H "X-Signature: $REQUEST_SIGNATURE" --json @request.json \
  "https://veil.rip/v1/identities/1/alerts"

Risposta#

HTTP 201application/json

L’avviso, la sua voce e la sua prova.

Campo	Tipo	Significato
`id`	`integer`	La posizione della voce nel registro: l’id permanente della dichiarazione.
`kind`	`string`	statement oppure alert.
`n`	`integer`	La scheda che fa la dichiarazione.
`signer`	`object`	n e token della scheda di persona la cui chiave ha firmato: la scheda stessa, o un proprietario o amministratore di un’organizzazione.
`statement`	`string`	La dichiarazione come è stata firmata, in JSON canonico. I suoi campi sono ripetuti sotto per mostrarli.
`salt`	`string`	32 byte in hex: c della voce è SHA-256(salt ‖ statement).
`entry`	`string`	La voce del registro con la firma, come il registro la tiene.
`i`	`integer`	La posizione della voce nel registro (la stessa di id).
`publishedAt`	`string \| null`	La prima controfirma sul primo checkpoint che contiene la voce.
`checkpoint`	`object \| null`	size e note del checkpoint controfirmato che data la voce. Null quando il registro non si legge.
`inclusion`	`array<string> \| null`	La prova di inclusione RFC 6962 della voce in quel checkpoint, in hex, dal più profondo.
`platform`	`string`	La piattaforma dell’account.
`subject`	`string`	L’id stabile dell’account, come lo prende GET /v1/lookup.
`display`	`string`	Il nome che la scheda mostra per l’account.
`state`	`string`	stolen, abandoned, moved oppure regained.
`since`	`string \| null`	Per stolen: la data del furto, AAAA-MM-GG.
`to`	`object \| null`	Per moved: handle, e subject quando il nuovo account è collegato alla scheda.
`logIndex`	`integer`	La posizione della voce nel registro.

Intestazioni della risposta#

Intestazione	Valore	Significato
`Content-Type`	`application/json`	Usa il tipo dichiarato per scegliere come leggere il corpo.
`Date`	`HTTP date`	Ora del server. Confrontala con il tuo orologio per firmare le richieste.
`Cache-Control`	`no-store`	Richiedila ogni volta: una dichiarazione o un avviso nuovi si vedono subito.

Note d’uso#

Firmata da una chiave attiva della persona: una chiave di dispositivo o la chiave di recupero del file di backup, quella che resta quando un dispositivo è stato rubato insieme all’account.
Al più 10 avvisi per scheda in 24 ore. Le organizzazioni non ne hanno.

Errori#

Gli errori API restituiscono un oggetto error. Usa error.code nella logica del programma; error.message è un testo inglese per le persone e può cambiare. Guida a risposte ed errori

HTTP	Codice	Significato e cosa fare
400	`invalid_parameter`	Un campo del percorso, della query o del corpo manca, è malformato o fuori intervallo. Correggi il campo indicato in `error.message` prima di inviare di nuovo.
400	`wrong_format`	La richiesta o la lettura appartiene all’altro formato del registro di questo server: un record v1 su un registro in formato 2, o una lettura del formato 2 su un registro in formato 1. Leggi `format` in GET /v1/log (assente vuol dire 1) e manda la forma di quel formato.
403	`identity_banned`	La scheda che agisce è sospesa dallo staff di Veil. Attendi la fine della restrizione o chiedi allo staff di riesaminarla.
403	`key_banned`	La chiave del dispositivo che firma è sospesa dallo staff di Veil. Usa una chiave attiva autorizzata o chiedi allo staff di riesaminare la restrizione.
403	`key_mismatch`	La chiave di firma non è autorizzata per questa scheda o operazione. Usa una chiave di dispositivo attiva con il ruolo di titolare o membro richiesto.
404	`not_found`	La scheda, la chiave, l’alias, il codice o la risorsa richiesti non sono stati trovati. Controlla l’identificatore. Codici e anteprime temporanei potrebbero essere scaduti o già usati.
409	`action_pending`	Un avviso precedente sullo stesso account, o un’azione dello staff della stessa famiglia, aspetta ancora il registro. Riprova quando è pubblicato, entro qualche minuto.
409	`alert_in_force`	L’account ha già questo stesso avviso. Non serve altro. Per correggere la data o il nuovo account, manda l’avviso con i dati nuovi.
409	`alert_not_in_force`	`regained` chiude un avviso, e l’account non ne ha uno in vigore. Leggi gli avvisi della scheda (GET /v1/identities/{n}/alerts) prima di chiuderne uno.
409	`erase_pending`	Su un registro in formato 2 la scheda ha una cancellazione in attesa. La sua chiusura firmata nomina la versione corrente, quindi la scheda non pubblica finché la cancellazione non è annullata. Annulla la cancellazione con POST /v1/identities/{n}/erase/cancel, poi pubblica la versione.
409	`signer_stale`	Su un registro in formato 2 `signer.n` di una voce firmata è indietro rispetto alla versione corrente della scheda che firma. Rileggi la scheda che firma e firma di nuovo la voce con la sua versione corrente in `signer.n`.
410	`erased`	La scheda esisteva ed è stata cancellata o rimossa. La risposta contiene anche la ricevuta pubblica di cancellazione. Smetti di usare questa scheda come autorità corrente. Conserva soltanto la ricevuta pubblica se serve.
422	`account_not_linked`	L’avviso riguarda un account che la scheda non ha, oppure `to.subject` non è un altro account della scheda sulla stessa piattaforma. Indica un account collegato, oppure lascia `to.subject` null e scrivi il nuovo nome.
422	`bad_entry`	Su un registro in formato 2 `salt`, `entry` o `closing` di una richiesta non vanno bene. `error.message` nomina il campo. Correggi il campo indicato, firma di nuovo la voce con la chiave della richiesta e manda una nuova richiesta firmata.
422	`invalid_statement`	Un avviso o una dichiarazione di una scheda non rispetta lo schema: un campo mancante o in più, un testo troppo lungo o con caratteri nascosti, un link non https, una data nel futuro. Correggi il campo indicato in `error.message` e firma di nuovo la dichiarazione e la sua voce.
422	`not_a_person`	La scheda è un’organizzazione dove è richiesta una persona. Usa l’endpoint delle organizzazioni oppure la scheda di una persona idonea.
429	`alert_quota`	La scheda ha fatto 10 avvisi sugli account nelle ultime 24 ore. Aspetta i secondi indicati da `Retry-After`.
503	`log_unavailable`	Al momento il registro pubblico non può essere letto, verificato o usato per pubblicare. Per le letture, considera il risultato non verificato e riprova più tardi. Prima di ripetere una scrittura, leggi la scheda per controllare se la pubblicazione è terminata.

Errori comuni delle richieste

HTTP	Codice	Significato e cosa fare
400	`invalid_json`	Il corpo non è un oggetto JSON, contiene chiavi duplicate o dati finali. Invia un solo oggetto JSON valido con `Content-Type` application/json.
400	`invalid_nonce`	Il nonce della richiesta firmata ha un formato errato. Genera un nuovo nonce da 16 a 128 caratteri usando lettere, cifre, _ o -.
400	`invalid_signature_alg`	`X-Signature-Alg` non è supportato. Usa un algoritmo di firma supportato e la codifica corretta per chiave e firma.
400	`invalid_timestamp`	Il timestamp della richiesta firmata non è espresso in millisecondi Unix. Usa un timestamp Unix intero in millisecondi e firma la richiesta corretta.
401	`invalid_signature`	La firma della richiesta HTTP non è valida. Firma metodo, percorso e byte del corpo esatti, senza modificarli dopo.
401	`missing_signature`	La richiesta richiede una firma del dispositivo e le intestazioni mancano o non sono leggibili. Invia `X-Public-Key`, `X-Signature` e i metadati della richiesta firmata. Una chiave API non sostituisce la firma del dispositivo.
401	`stale_timestamp`	Il timestamp firmato è fuori dalla finestra temporale ammessa. Confronta l’intestazione Date del server con il tuo orologio, poi genera nuovi nonce, timestamp e firma.
409	`replayed_nonce`	La chiave di firma ha già usato questo nonce. Controlla se la richiesta precedente è riuscita prima di crearne una nuova firmata.
413	`payload_too_large`	Il corpo della richiesta supera il limite in byte dell’endpoint. Riduci il corpo codificato. La gestione delle chiavi API ammette al massimo 8 KiB.
429	`rate_limited`	È stato superato un limite anonimo, delle richieste firmate o della chiave API. Attendi almeno i secondi indicati da `Retry-After`. Condividi coda e budget dei tentativi tra i tuoi processi.
500	`internal_error`	Si è verificato un errore imprevisto del server. I dettagli interni non vengono restituiti. Riprova le letture con attese crescenti e un limite. Controlla l’esito delle scritture prima di inviare una nuova operazione firmata.
503	`busy`	L’applicazione ha raggiunto un limite temporaneo di concorrenza o del database. Attendi i secondi indicati da `Retry-After` e riprova con attese crescenti e un limite.

Leggi questa voce in JSON