# Démo Oracle — guide administrateur

## Installer le module

Le module s'installe comme tout module **sw** :

1. déposer le dossier `demo_oracle/` sous `mon-appli/modules/` — par ZIP depuis
   *Administration » Modules*, ou comme sous-module git ;
2. l'activer dans *Administration » Modules*.

Le nom du dossier **doit rester `demo_oracle`**, identique à la clé `name` du
descripteur : le garde-fou de mise à jour par ZIP
(`mon-appli/admin/modules.php`) refuse une archive dont le dossier ne
correspond pas.

Le module n'a **aucune dépendance** (`depends_on` vide). Il ne requiert pas le
module Oracle et ne partage aucun fichier avec lui.

### Prérequis

| Élément | Détail |
| --- | --- |
| PHP | 8.2 ou supérieur |
| Extension `oci8` | obligatoire — sans elle le module refuse la connexion et le dit |
| Extension `zip` | nécessaire uniquement pour déposer un portefeuille Oracle Cloud |
| Oracle Instant Client | 19c, avec `LD_LIBRARY_PATH` (Linux) ou `PATH` (Windows) renseigné |

Sous Windows, le `PATH` n'est lu qu'au démarrage du processus : **redémarrer
Apache** après avoir ajouté l'Instant Client.

## Attribuer les rôles

L'activation insère deux rôles dans le catalogue :

| Rôle | Ce qu'il permet |
| --- | --- |
| `demo_oracle_admin` | déclarer et modifier les bases, régler le module |
| `demo_oracle_user` | consulter les rapports |

`app_admin` est un super-rôle implicite : il couvre les deux.

Les comptes créés par LDAP ou OAuth arrivent **sans aucun rôle** ; l'attribution
est manuelle, dans *Administration » Utilisateurs*.

## Déclarer les bases de démonstration

*Démo Oracle » Gérer les bases*, puis **Ajouter une base**. Cinq au maximum ;
au-delà, le bouton se grise et une pastille rappelle la limite.

| Champ | Remarque |
| --- | --- |
| Nom | libellé affiché ; libre |
| Type de connexion | **directe** (hôte, port, service) ou **Oracle Cloud** (portefeuille) |
| Utilisateur, mot de passe | **chiffrés au repos** (voir plus bas) |
| SYSDBA | à éviter : la démonstration n'en a pas besoin |
| Description | facultatif, affiché dans la liste |

### Une base Oracle Cloud

Une base Autonomous ne se joint pas par hôte et service : elle se joint par un
**alias TNS**, résolu grâce au **portefeuille** téléchargé depuis la console
OCI.

1. Choisissez **Oracle Cloud (portefeuille)** comme type de connexion.
2. Déposez l'archive ZIP du portefeuille, telle qu'OCI la fournit.
3. Saisissez l'alias TNS — `..._high`, `..._medium` ou `..._low`. Après le
   premier enregistrement, le champ propose les alias lus dans le
   `tnsnames.ora` du portefeuille : plus besoin de les retenir.
4. Enregistrez, puis **testez la connexion**. Dans cet ordre : le portefeuille
   doit être extrait avant qu'on puisse s'en servir, le test le rappelle.

Ce que le module fait de l'archive :

- il l'**inspecte avant d'extraire**. Une entrée dont le chemin contient `..`
  fait rejeter l'archive entière — c'est la traversée de répertoire classique
  du ZIP, contre laquelle `extractTo()` ne protège pas ;
- il n'extrait que les fichiers attendus d'un portefeuille : `tnsnames.ora`,
  `sqlnet.ora`, les magasins de clés. Un `.php` glissé dans l'archive est
  ignoré ;
- il plafonne la taille décompressée ;
- il refuse une archive sans `tnsnames.ora` : ce n'est pas un portefeuille ;
- il extrait **à plat**, sous `securite/demo_oracle_wallets/<id>/`, donc **hors
  du DocumentRoot** : les clés ne sont jamais servies par Apache ;
- il réécrit `DIRECTORY` dans `sqlnet.ora`. Le fichier livré par OCI pointe
  vers le répertoire de la machine qui a téléchargé l'archive ; sans cette
  correction, OCI8 chercherait les clés là-bas.

Le portefeuille est supprimé avec la fiche, et remplacé — pas fusionné — quand
vous en déposez un nouveau. Basculer une base de « Cloud » vers « directe »
efface aussi le portefeuille devenu inutile.

Une base Cloud est réputée disposer du **Diagnostic Pack** : Oracle l'inclut
dans Autonomous, et le paramètre d'instance ne le dit pas toujours. Les
rapports temps réel et historique y fonctionnent donc directement.

Comme partout dans **sw**, le formulaire de modification **ne réaffiche pas**
le mot de passe : laissé vide, l'ancien est conservé.

### Tester la connexion

Le bouton **Tester la connexion**, à côté d'« Enregistrer », ouvre une
connexion réelle et affiche le résultat sans quitter le formulaire — la saisie
en cours n'est pas perdue. En cas d'échec, le message `ORA-` d'Oracle est
repris tel quel.

En cas de succès, le test rapporte la version de la base et trois éléments qui
décident de ce que la démonstration pourra montrer :

| Ligne | Ce qu'elle conditionne |
| --- | --- |
| Diagnostic Pack | l'activité temps réel et l'historique lisent `GV$ACTIVE_SESSION_HISTORY` — toujours vrai sur une base Autonomous |
| `sw$bash_snapper` | le repli utilisé quand le Diagnostic Pack n'est pas sous licence |
| Rôle DBA | rien — l'information est donnée, elle n'empêche jamais l'enregistrement |

Si **ni** le Diagnostic Pack **ni** `sw$bash_snapper` ne sont disponibles, le
test le signale : les rapports temps réel et historique s'afficheront, mais
sans données. Les autres rapports fonctionneront normalement.

Sur une base déjà enregistrée, il est inutile de retaper le mot de passe : le
test relit la valeur stockée, comme le fait l'enregistrement. Sur une base
Cloud, le test suppose la fiche déjà enregistrée — le portefeuille doit exister
sur le disque.

Ce test est réservé aux porteurs du rôle `demo_oracle_admin`. Ce n'est pas une
précaution de façade : un point d'entrée qui ouvre une connexion TCP vers un
hôte fourni par le navigateur ferait du serveur web un connecteur sortant, de
quoi balayer un réseau interne depuis l'extérieur.

### Le compte Oracle à utiliser

Un compte de **lecture seule** suffit et est recommandé. Les vues interrogées
sont les vues dynamiques et le référentiel (`V$…`, `DBA_…`). Accorder plus que
`SELECT` n'apporte rien : le module ne sait rien écrire.

C'est pourquoi le test de connexion **signale** l'absence du rôle DBA sans la
traiter comme une erreur, là où le module Oracle complet refuse la connexion :
lui en a besoin pour ses actions, la démonstration non.

## Configurer le module

*Démo Oracle » Configuration de la démonstration* — un seul réglage :

**URL « version complète »**. C'est la cible de toutes les mentions
« disponible seulement dans la version complète ». Laissée vide, ces mentions
restent de simples explications, sans lien : la démonstration s'installe alors
sans renvoi commercial.

La valeur est stockée dans `securite/modules/demo_oracle.json`
(`Module::getConfig` / `updateConfig`).

Les limites, elles, **ne se règlent pas** : elles sont dans le code
(`lib/DemoOracleConfig.php`). C'est délibéré — une limite réglable depuis
l'interface serait une limite contournable par qui accède à l'interface.

## Chiffrement des secrets

Les mots de passe des bases passent par `lib/Crypto`
(`sodium_crypto_secretbox`), comme partout dans l'application. Deux
conséquences opérationnelles :

- l'extension PHP **`sodium`** est obligatoire — `lib/Crypto` lève une
  exception explicite si elle manque ;
- `securite/master.key` doit être sauvegardé **en même temps** que
  `securite/database.sqlite`. Le perdre rend les mots de passe irrécupérables.

## Exposer la démonstration sur Internet

C'est l'usage prévu, et le module est conçu pour l'encaisser :

- **aucun gestionnaire d'action** n'existe côté serveur. Un `POST` forgé vers
  `report.php` ne trouve rien à déclencher ;
- le fichier `.htaccess` du module refuse `manifest.json`, `module.php` et tout
  fichier commençant par `_` (les partiels de rapport). Cette protection est
  portée par le module lui-même, parce que la règle équivalente du cœur ne
  couvre que `modules/oracle/`.

Deux précautions restent de votre ressort :

1. servir le site en **HTTPS** ;
2. donner au compte Oracle de démonstration le **strict minimum** de droits, et
   le faire pointer vers une base qui ne contient rien de confidentiel — les
   rapports affichent des textes SQL, donc potentiellement des noms de tables
   et de colonnes.

## Ce qu'il faut savoir avant de déboguer

- Le module rend sa **propre** barre de navigation. Les barres latérales Oracle
  et PostgreSQL sont codées en dur dans `mon-appli/includes/header.php`,
  c'est-à-dire dans le dépôt du cœur : un troisième module ne peut pas s'y
  ajouter sans modifier le dépôt principal.
- Le module crée sa **propre** table, `demo_oracle_databases`
  (`DemoOracleSchema::ensure()`), appelée à chaque bootstrap et idempotente.
  Les tables `oracle_*` sont créées par `lib/Database.php`, dans le cœur.
- Toutes les fonctions du module sont préfixées `demo_` : elles coexistent avec
  celles du module Oracle sans collision si les deux sont installés.
