Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX/Object.pm

   1 package File::KDBX::Object;
   2 # ABSTRACT: A KDBX database object
   3
   4 use warnings;
   5 use strict;
   6
   7 use Devel::GlobalDestruction;
   8 use File::KDBX::Constants qw(:bool);
   9 use File::KDBX::Error;
  10 use File::KDBX::Util qw(:uuid);
  11 use Hash::Util::FieldHash qw(fieldhashes);
  12 use List::Util qw(any first);
  13 use Ref::Util qw(is_arrayref is_plain_arrayref is_plain_hashref is_ref);
  14 use Scalar::Util qw(blessed weaken);
  15 use namespace::clean;
  16
  17 our $VERSION = '999.999'; # VERSION
  18
  19 fieldhashes \my (%KDBX, %PARENT, %TXNS, %REFS, %SIGNALS);
  20
  21 =method new
  22
  23     $object = File::KDBX::Object->new;
  24     $object = File::KDBX::Object->new(%attributes);
  25     $object = File::KDBX::Object->new(\%data);
  26     $object = File::KDBX::Object->new(\%data, $kdbx);
  27
  28 Construct a new KDBX object.
  29
  30 There is a subtlety to take note of. There is a significant difference between:
  31
  32     File::KDBX::Entry->new(username => 'iambatman');
  33
  34 and:
  35
  36     File::KDBX::Entry->new({username => 'iambatman'}); # WRONG
  37
  38 In the first, an empty object is first created and then initialized with whatever I<attributes> are given. In
  39 the second, a hashref is blessed and essentially becomes the object. The significance is that the hashref
  40 key-value pairs will remain as-is so the structure is expected to adhere to the shape of a raw B<Object>
  41 (which varies based on the type of object), whereas with the first the attributes will set the structure in
  42 the correct way (just like using the object accessors / getters / setters).
  43
  44 The second example isn't I<generally> wrong -- this type of construction is supported for a reason, to allow
  45 for working with KDBX objects at a low level -- but it is wrong in this specific case only because
  46 C<< {username => $str} >> isn't a valid raw KDBX entry object. The L</username> attribute is really a proxy
  47 for the C<UserName> string, so the equivalent raw entry object should be
  48 C<< {strings => {UserName => {value => $str}}} >>. These are roughly equivalent:
  49
  50     File::KDBX::Entry->new(username => 'iambatman');
  51     File::KDBX::Entry->new({strings => {UserName => {value => 'iambatman'}}});
  52
  53 If this explanation went over your head, that's fine. Just stick with the attributes since they are typically
  54 easier to use correctly and provide the most convenience. If in the future you think of some kind of KDBX
  55 object manipulation you want to do that isn't supported by the accessors and methods, just know you I<can>
  56 access an object's data directly.
  57
  58 =cut
  59
  60 sub new {
  61     my $class = shift;
  62
  63     # copy constructor
  64     return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
  65
  66     my $data;
  67     $data = shift if is_plain_hashref($_[0]);
  68
  69     my $kdbx;
  70     $kdbx = shift if @_ % 2 == 1;
  71
  72     my %args = @_;
  73     $args{kdbx} //= $kdbx if defined $kdbx;
  74
  75     my $self = bless $data // {}, $class;
  76     $self->init(%args);
  77     $self->_set_nonlazy_attributes if !$data;
  78     return $self;
  79 }
  80
  81 sub _set_nonlazy_attributes { die 'Not implemented' }
  82
  83 =method init
  84
  85     $object = $object->init(%attributes);
  86
  87 Called by the constructor to set attributes. You normally should not call this.
  88
  89 =cut
  90
  91 sub init {
  92     my $self = shift;
  93     my %args = @_;
  94
  95     while (my ($key, $val) = each %args) {
  96         if (my $method = $self->can($key)) {
  97             $self->$method($val);
  98         }
  99     }
 100
 101     return $self;
 102 }
 103
 104 =method wrap
 105
 106     $object = File::KDBX::Object->wrap($object);
 107
 108 Ensure that a KDBX object is blessed.
 109
 110 =cut
 111
 112 sub wrap {
 113     my $class   = shift;
 114     my $object  = shift;
 115     return $object if blessed $object && $object->isa($class);
 116     return $class->new(@_, @$object) if is_arrayref($object);
 117     return $class->new($object, @_);
 118 }
 119
 120 =method label
 121
 122     $label = $object->label;
 123     $object->label($label);
 124
 125 Get or set the object's label, a text string that can act as a non-unique identifier. For an entry, the label
 126 is its title string. For a group, the label is its name.
 127
 128 =cut
 129
 130 sub label { die 'Not implemented' }
 131
 132 =method clone
 133
 134     $object_copy = $object->clone;
 135     $object_copy = File::KDBX::Object->new($object);
 136
 137 Make a clone of an object. By default the clone is indeed an exact copy that is connected to the same database
 138 but not actually included in the object tree (i.e. it has no parent). Some options are allowed to get
 139 different effects:
 140
 141 =for :list
 142 * C<new_uuid> - If set, generate a new UUID for the copy (default: false)
 143 * C<parent> - If set, add the copy to the same parent group, if any (default: false)
 144 * C<relabel> - If set, append " - Copy" to the object's title or name (default: false)
 145 * C<entries> - If set, copy child entries, if any (default: true)
 146 * C<groups> - If set, copy child groups, if any (default: true)
 147 * C<history> - If set, copy entry history, if any (default: true)
 148 * C<reference_password> - Toggle whether or not cloned entry's Password string should be set as a field
 149     reference to the original entry's Password string (default: false)
 150 * C<reference_username> - Toggle whether or not cloned entry's UserName string should be set as a field
 151     reference to the original entry's UserName string (default: false)
 152
 153 =cut
 154
 155 my %CLONE = (entries => 1, groups => 1, history => 1);
 156 sub clone {
 157     my $self = shift;
 158     my %args = @_;
 159
 160     local $CLONE{new_uuid}              = $args{new_uuid} // $args{parent} // 0;
 161     local $CLONE{entries}               = $args{entries}  // 1;
 162     local $CLONE{groups}                = $args{groups}   // 1;
 163     local $CLONE{history}               = $args{history}  // 1;
 164     local $CLONE{reference_password}    = $args{reference_password} // 0;
 165     local $CLONE{reference_username}    = $args{reference_username} // 0;
 166
 167     require Storable;
 168     my $copy = Storable::dclone($self);
 169
 170     if ($args{relabel} and my $label = $self->label) {
 171         $copy->label("$label - Copy");
 172     }
 173     if ($args{parent} and my $parent = $self->parent) {
 174         $parent->add_object($copy);
 175     }
 176
 177     return $copy;
 178 }
 179
 180 sub STORABLE_freeze {
 181     my $self    = shift;
 182     my $cloning = shift;
 183
 184     my $copy = {%$self};
 185     delete $copy->{entries} if !$CLONE{entries};
 186     delete $copy->{groups}  if !$CLONE{groups};
 187     delete $copy->{history} if !$CLONE{history};
 188
 189     return ($cloning ? Hash::Util::FieldHash::id($self) : ''), $copy;
 190 }
 191
 192 sub STORABLE_thaw {
 193     my $self    = shift;
 194     my $cloning = shift;
 195     my $addr    = shift;
 196     my $copy    = shift;
 197
 198     @$self{keys %$copy} = values %$copy;
 199
 200     if ($cloning) {
 201         my $kdbx = $KDBX{$addr};
 202         $self->kdbx($kdbx) if $kdbx;
 203     }
 204
 205     if (defined $self->{uuid}) {
 206         if (($CLONE{reference_password} || $CLONE{reference_username}) && $self->can('strings')) {
 207             my $uuid = format_uuid($self->{uuid});
 208             my $clone_obj = do {
 209                 local $CLONE{new_uuid}              = 0;
 210                 local $CLONE{entries}               = 1;
 211                 local $CLONE{groups}                = 1;
 212                 local $CLONE{history}               = 1;
 213                 local $CLONE{reference_password}    = 0;
 214                 local $CLONE{reference_username}    = 0;
 215                 # Clone only the entry's data and manually bless to avoid infinite recursion.
 216                 bless Storable::dclone({%$copy}), 'File::KDBX::Entry';
 217             };
 218             my $txn = $self->begin_work(snapshot => $clone_obj);
 219             if ($CLONE{reference_password}) {
 220                 $self->password("{REF:P\@I:$uuid}");
 221             }
 222             if ($CLONE{reference_username}) {
 223                 $self->username("{REF:U\@I:$uuid}");
 224             }
 225             $txn->commit;
 226         }
 227         $self->uuid(generate_uuid) if $CLONE{new_uuid};
 228     }
 229
 230     # Dualvars aren't cloned as dualvars, so dualify the icon.
 231     $self->icon_id($self->{icon_id}) if defined $self->{icon_id};
 232 }
 233
 234 =attr kdbx
 235
 236     $kdbx = $object->kdbx;
 237     $object->kdbx($kdbx);
 238
 239 Get or set the L<File::KDBX> instance connected with this object.
 240
 241 =cut
 242
 243 sub kdbx {
 244     my $self = shift;
 245     $self = $self->new if !ref $self;
 246     if (@_) {
 247         if (my $kdbx = shift) {
 248             $KDBX{$self} = $kdbx;
 249             weaken $KDBX{$self};
 250         }
 251         else {
 252             delete $KDBX{$self};
 253         }
 254     }
 255     $KDBX{$self} or throw 'Object is disconnected', object => $self;
 256 }
 257
 258 =method is_connected
 259
 260     $bool = $object->is_connected;
 261
 262 Determine whether or not an object is connected to a database.
 263
 264 =cut
 265
 266 sub is_connected {
 267     my $self = shift;
 268     return !!eval { $self->kdbx };
 269 }
 270
 271 =method id
 272
 273     $string_uuid = $object->id;
 274     $string_uuid = $object->id($delimiter);
 275
 276 Get the unique identifier for this object as a B<formatted> UUID string, typically for display purposes. You
 277 could use this to compare with other identifiers formatted with the same delimiter, but it is more efficient
 278 to use the raw UUID for that purpose (see L</uuid>).
 279
 280 A delimiter can optionally be provided to break up the UUID string visually. See
 281 L<File::KDBX::Util/format_uuid>.
 282
 283 =cut
 284
 285 sub id { format_uuid(shift->uuid, @_) }
 286
 287 =method group
 288
 289 =method parent
 290
 291     $group = $object->group;
 292     # OR equivalently
 293     $group = $object->parent;
 294
 295     $object->group($new_parent);
 296
 297 Get or set the parent group to which an object belongs or C<undef> if it belongs to no group.
 298
 299 =cut
 300
 301 sub group {
 302     my $self = shift;
 303
 304     if (my $new_group = shift) {
 305         my $old_group = $self->group;
 306         return $new_group if Hash::Util::FieldHash::id($old_group) == Hash::Util::FieldHash::id($new_group);
 307         # move to a new parent
 308         $self->remove(signal => 0) if $old_group;
 309         $new_group->add_object($self);
 310     }
 311
 312     my $id   = Hash::Util::FieldHash::id($self);
 313     if (my $group = $PARENT{$self}) {
 314         my $method = $self->_parent_container;
 315         return $group if first { $id == Hash::Util::FieldHash::id($_) } @{$group->$method};
 316         delete $PARENT{$self};
 317     }
 318     # always get lineage from root to leaf because the other way requires parent, so it would be recursive
 319     my $lineage = $self->kdbx->_trace_lineage($self) or return;
 320     my $group = pop @$lineage or return;
 321     $PARENT{$self} = $group; weaken $PARENT{$self};
 322     return $group;
 323 }
 324
 325 sub parent { shift->group(@_) }
 326
 327 sub _set_group {
 328     my $self = shift;
 329     if (my $parent = shift) {
 330         $PARENT{$self} = $parent;
 331         weaken $PARENT{$self};
 332     }
 333     else {
 334         delete $PARENT{$self};
 335     }
 336     return $self;
 337 }
 338
 339 ### Name of the parent attribute expected to contain the object
 340 sub _parent_container { die 'Not implemented' }
 341
 342 =method lineage
 343
 344     \@lineage = $object->lineage;
 345     \@lineage = $object->lineage($base_group);
 346
 347 Get the direct line of ancestors from C<$base_group> (default: the root group) to an object. The lineage
 348 includes the base group but I<not> the target object. Returns C<undef> if the target is not in the database
 349 structure. Returns an empty arrayref is the object itself is a root group.
 350
 351 =cut
 352
 353 sub lineage {
 354     my $self = shift;
 355     my $base = shift;
 356
 357     my $base_addr = $base ? Hash::Util::FieldHash::id($base) : 0;
 358
 359     # try leaf to root
 360     my @path;
 361     my $o = $self;
 362     while ($o = $o->parent) {
 363         unshift @path, $o;
 364         last if $base_addr == Hash::Util::FieldHash::id($o);
 365     }
 366     return \@path if @path && ($base_addr == Hash::Util::FieldHash::id($path[0]) || $path[0]->is_root);
 367
 368     # try root to leaf
 369     return $self->kdbx->_trace_lineage($self, $base);
 370 }
 371
 372 =method remove
 373
 374     $object = $object->remove(%options);
 375
 376 Remove an object from its parent. If the object is a group, all contained objects stay with the object and so
 377 are removed as well. Options:
 378
 379 =for :list
 380 * C<signal> Whether or not to signal the removal to the connected database (default: true)
 381
 382 =cut
 383
 384 sub remove {
 385     my $self = shift;
 386     my $parent = $self->parent;
 387     $parent->remove_object($self, @_) if $parent;
 388     $self->_set_group(undef);
 389     return $self;
 390 }
 391
 392 =method recycle
 393
 394     $object = $object->recycle;
 395
 396 Remove an object from its parent and add it to the connected database's recycle bin group.
 397
 398 =cut
 399
 400 sub recycle {
 401     my $self = shift;
 402     return $self->parent($self->kdbx->recycle_bin);
 403 }
 404
 405 =method recycle_or_remove
 406
 407     $object = $object->recycle_or_remove;
 408
 409 Recycle or remove an object, depending on the connected database's L<File::KDBX/recycle_bin_enabled>. If the
 410 object is not connected to a database or is already in the recycle bin, remove it.
 411
 412 =cut
 413
 414 sub recycle_or_remove {
 415     my $self = shift;
 416     my $kdbx = eval { $self->kdbx };
 417     if ($kdbx && $kdbx->recycle_bin_enabled && !$self->is_recycled) {
 418         $self->recycle;
 419     }
 420     else {
 421         $self->remove;
 422     }
 423 }
 424
 425 =method is_recycled
 426
 427     $bool = $object->is_recycled;
 428
 429 Get whether or not an object is in a recycle bin.
 430
 431 =cut
 432
 433 sub is_recycled {
 434     my $self = shift;
 435     eval { $self->kdbx } or return FALSE;
 436     return !!($self->parent && any { $_->is_recycle_bin } @{$self->lineage});
 437 }
 438
 439 ##############################################################################
 440
 441 =method tag_list
 442
 443     @tags = $entry->tag_list;
 444
 445 Get a list of tags, split from L</tag> using delimiters C<,>, C<.>, C<:>, C<;> and whitespace.
 446
 447 =cut
 448
 449 sub tag_list {
 450     my $self = shift;
 451     return grep { $_ ne '' } split(/[,\.:;]|\s+/, trim($self->tags) // '');
 452 }
 453
 454 =method custom_icon
 455
 456     $image_data = $object->custom_icon;
 457     $image_data = $object->custom_icon($image_data, %attributes);
 458
 459 Get or set an icon image. Returns C<undef> if there is no custom icon set. Setting a custom icon will change
 460 the L</custom_icon_uuid> attribute.
 461
 462 Custom icon attributes (supported in KDBX4.1 and greater):
 463
 464 =for :list
 465 * C<name> - Name of the icon (text)
 466 * C<last_modification_time> - Just what it says (datetime)
 467
 468 =cut
 469
 470 sub custom_icon {
 471     my $self = shift;
 472     my $kdbx = $self->kdbx;
 473     if (@_) {
 474         my $img = shift;
 475         my $uuid = defined $img ? $kdbx->add_custom_icon($img, @_) : undef;
 476         $self->icon_id(0) if $uuid;
 477         $self->custom_icon_uuid($uuid);
 478         return $img;
 479     }
 480     return $kdbx->custom_icon_data($self->custom_icon_uuid);
 481 }
 482
 483 =method custom_data
 484
 485     \%all_data = $object->custom_data;
 486     $object->custom_data(\%all_data);
 487
 488     \%data = $object->custom_data($key);
 489     $object->custom_data($key => \%data);
 490     $object->custom_data(%data);
 491     $object->custom_data(key => $value, %data);
 492
 493 Get and set custom data. Custom data is metadata associated with an object.
 494
 495 Each data item can have a few attributes associated with it.
 496
 497 =for :list
 498 * C<key> - A unique text string identifier used to look up the data item (required)
 499 * C<value> - A text string value (required)
 500 * C<last_modification_time> (optional, KDBX4.1+)
 501
 502 =cut
 503
 504 sub custom_data {
 505     my $self = shift;
 506     $self->{custom_data} = shift if @_ == 1 && is_plain_hashref($_[0]);
 507     return $self->{custom_data} //= {} if !@_;
 508
 509     my %args = @_     == 2 ? (key => shift, value => shift)
 510              : @_ % 2 == 1 ? (key => shift, @_) : @_;
 511
 512     if (!$args{key} && !$args{value}) {
 513         my %standard = (key => 1, value => 1, last_modification_time => 1);
 514         my @other_keys = grep { !$standard{$_} } keys %args;
 515         if (@other_keys == 1) {
 516             my $key = $args{key} = $other_keys[0];
 517             $args{value} = delete $args{$key};
 518         }
 519     }
 520
 521     my $key = $args{key} or throw 'Must provide a custom_data key to access';
 522
 523     return $self->{custom_data}{$key} = $args{value} if is_plain_hashref($args{value});
 524
 525     while (my ($field, $value) = each %args) {
 526         $self->{custom_data}{$key}{$field} = $value;
 527     }
 528     return $self->{custom_data}{$key};
 529 }
 530
 531 =method custom_data_value
 532
 533     $value = $object->custom_data_value($key);
 534
 535 Exactly the same as L</custom_data> except returns just the custom data's value rather than a structure of
 536 attributes. This is a shortcut for:
 537
 538     my $data = $object->custom_data($key);
 539     my $value = defined $data ? $data->{value} : undef;
 540
 541 =cut
 542
 543 sub custom_data_value {
 544     my $self = shift;
 545     my $data = $self->custom_data(@_) // return undef;
 546     return $data->{value};
 547 }
 548
 549 ##############################################################################
 550
 551 =method begin_work
 552
 553     $txn = $object->begin_work(%options);
 554     $object->begin_work(%options);
 555
 556 Begin a new transaction. Returns a L<File::KDBX::Transaction> object that can be scoped to ensure a rollback
 557 occurs if exceptions are thrown. Alternatively, if called in void context, there will be no
 558 B<File::KDBX::Transaction> and it is instead your responsibility to call L</commit> or L</rollback> as
 559 appropriate. It is undefined behavior to call these if a B<File::KDBX::Transaction> exists. Recursive
 560 transactions are allowed.
 561
 562 Signals created during a transaction are delayed until all transactions are resolved. If the outermost
 563 transaction is committed, then the signals are de-duplicated and delivered. Otherwise the signals are dropped.
 564 This means that the KDBX database will not fix broken references or mark itself dirty until after the
 565 transaction is committed.
 566
 567 How it works: With the beginning of a transaction, a snapshot of the object is created. In the event of
 568 a rollback, the object's data is replaced with data from the snapshot.
 569
 570 By default, the snapshot is shallow (i.e. does not include subroups, entries or historical entries). This
 571 means that only modifications to the object itself (its data, fields, strings, etc.) are atomic; modifications
 572 to subroups etc., including adding or removing items, are auto-committed instantly and will persist regardless
 573 of the result of the pending transaction. You can override this for groups, entries and history independently
 574 using options:
 575
 576 =for :list
 577 * C<entries> - If set, snapshot entries within a group, deeply (default: false)
 578 * C<groups> - If set, snapshot subroups within a group, deeply (default: false)
 579 * C<history> - If set, snapshot historical entries within an entry (default: false)
 580
 581 For example, if you begin a transaction on a group object using the C<entries> option, like this:
 582
 583     $group->begin_work(entries => 1);
 584
 585 Then if you modify any of the group's entries OR add new entries OR delete entries, all of that will be undone
 586 if the transaction is rolled back. With a default-configured transaction, however, changes to entries are kept
 587 even if the transaction is rolled back.
 588
 589 =cut
 590
 591 sub begin_work {
 592     my $self = shift;
 593
 594     if (defined wantarray) {
 595         require File::KDBX::Transaction;
 596         return File::KDBX::Transaction->new($self, @_);
 597     }
 598
 599     my %args = @_;
 600     my $orig = $args{snapshot} // do {
 601         my $c = $self->clone(
 602             entries => $args{entries} // 0,
 603             groups  => $args{groups}  // 0,
 604             history => $args{history} // 0,
 605         );
 606         $c->{entries} = $self->{entries} if !$args{entries};
 607         $c->{groups}  = $self->{groups}  if !$args{groups};
 608         $c->{history} = $self->{history} if !$args{history};
 609         $c;
 610     };
 611
 612     my $id = Hash::Util::FieldHash::id($orig);
 613     _save_references($id, $self, $orig);
 614
 615     $self->_signal_begin_work;
 616
 617     push @{$self->_txns}, $orig;
 618 }
 619
 620 =method commit
 621
 622     $object->commit;
 623
 624 Commit a transaction, making updates to C<$object> permanent. Returns itself to allow method chaining.
 625
 626 =cut
 627
 628 sub commit {
 629     my $self = shift;
 630     my $orig = pop @{$self->_txns} or return $self;
 631     $self->_commit($orig);
 632     my $signals = $self->_signal_commit;
 633     $self->_signal_send($signals) if !$self->_in_txn;
 634     return $self;
 635 }
 636
 637 =method rollback
 638
 639     $object->rollback;
 640
 641 Roll back the most recent transaction, throwing away any updates to the L</object> made since the transaction
 642 began. Returns itself to allow method chaining.
 643
 644 =cut
 645
 646 sub rollback {
 647     my $self = shift;
 648
 649     my $orig = pop @{$self->_txns} or return $self;
 650
 651     my $id = Hash::Util::FieldHash::id($orig);
 652     _restore_references($id, $orig);
 653
 654     $self->_signal_rollback;
 655
 656     return $self;
 657 }
 658
 659 # Get whether or not there is at least one pending transaction.
 660 sub _in_txn { scalar @{$_[0]->_txns} }
 661
 662 # Get an array ref of pending transactions.
 663 sub _txns   { $TXNS{$_[0]} //= [] }
 664
 665 # The _commit hook notifies subclasses that a commit has occurred.
 666 sub _commit { die 'Not implemented' }
 667
 668 # Get a reference to an object that represents an object's committed state. If there is no pending
 669 # transaction, this is just $self. If there is a transaction, this is the snapshot take before the transaction
 670 # began. This method is private because it provides direct access to the actual snapshot. It is important that
 671 # the snapshot not be changed or a rollback would roll back to an altered state.
 672 # This is used by File::KDBX::Dumper::XML so as to not dump uncommitted changes.
 673 sub _committed {
 674     my $self = shift;
 675     my ($orig) = @{$self->_txns};
 676     return $orig // $self;
 677 }
 678
 679 # In addition to cloning an object when beginning work, we also keep track its hashrefs and arrayrefs
 680 # internally so that we can restore to the very same structures in the case of a rollback.
 681 sub _save_references {
 682     my $id   = shift;
 683     my $self = shift;
 684     my $orig = shift;
 685
 686     if (is_plain_arrayref($orig)) {
 687         for (my $i = 0; $i < @$orig; ++$i) {
 688             _save_references($id, $self->[$i], $orig->[$i]);
 689         }
 690         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 691     }
 692     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 693         for my $key (keys %$orig) {
 694             _save_references($id, $self->{$key}, $orig->{$key});
 695         }
 696         $REFS{$id}{Hash::Util::FieldHash::id($orig)} = $self;
 697     }
 698 }
 699
 700 # During a rollback, copy data from the snapshot back into the original internal structures.
 701 sub _restore_references {
 702     my $id   = shift;
 703     my $orig = shift // return;
 704     my $self = delete $REFS{$id}{Hash::Util::FieldHash::id($orig) // ''} // return $orig;
 705
 706     if (is_plain_arrayref($orig)) {
 707         @$self = map { _restore_references($id, $_) } @$orig;
 708     }
 709     elsif (is_plain_hashref($orig) || (blessed $orig && $orig->isa(__PACKAGE__))) {
 710         for my $key (keys %$orig) {
 711             # next if is_ref($orig->{$key}) &&
 712             #     (Hash::Util::FieldHash::id($self->{$key}) // 0) == Hash::Util::FieldHash::id($orig->{$key});
 713             $self->{$key} = _restore_references($id, $orig->{$key});
 714         }
 715     }
 716
 717     return $self;
 718 }
 719
 720 ##############################################################################
 721
 722 sub _signal {
 723     my $self = shift;
 724     my $type = shift;
 725
 726     if ($self->_in_txn) {
 727         my $stack = $self->_signal_stack;
 728         my $queue = $stack->[-1];
 729         push @$queue, [$type, @_];
 730     }
 731
 732     $self->_signal_send([[$type, @_]]);
 733
 734     return $self;
 735 }
 736
 737 sub _signal_stack { $SIGNALS{$_[0]} //= [] }
 738
 739 sub _signal_begin_work {
 740     my $self = shift;
 741     push @{$self->_signal_stack}, [];
 742 }
 743
 744 sub _signal_commit {
 745     my $self = shift;
 746     my $signals = pop @{$self->_signal_stack};
 747     my $previous = $self->_signal_stack->[-1] // [];
 748     push @$previous, @$signals;
 749     return $previous;
 750 }
 751
 752 sub _signal_rollback {
 753     my $self = shift;
 754     pop @{$self->_signal_stack};
 755 }
 756
 757 sub _signal_send {
 758     my $self    = shift;
 759     my $signals = shift // [];
 760
 761     my $kdbx = $KDBX{$self} or return;
 762
 763     # de-duplicate, keeping the most recent signal for each type
 764     my %seen;
 765     my @signals = grep { !$seen{$_->[0]}++ } reverse @$signals;
 766
 767     for my $sig (reverse @signals) {
 768         $kdbx->_handle_signal($self, @$sig);
 769     }
 770 }
 771
 772 ##############################################################################
 773
 774 sub _wrap_group {
 775     my $self  = shift;
 776     my $group = shift;
 777     require File::KDBX::Group;
 778     return File::KDBX::Group->wrap($group, $KDBX{$self});
 779 }
 780
 781 sub _wrap_entry {
 782     my $self  = shift;
 783     my $entry = shift;
 784     require File::KDBX::Entry;
 785     return File::KDBX::Entry->wrap($entry, $KDBX{$self});
 786 }
 787
 788 sub TO_JSON { +{%{$_[0]}} }
 789
 790 1;
 791 __END__
 792
 793 =for Pod::Coverage STORABLE_freeze STORABLE_thaw TO_JSON
 794
 795 =head1 DESCRIPTION
 796
 797 KDBX is an object database. This abstract class represents an object. You should not use this class directly
 798 but instead use its subclasses:
 799
 800 =for :list
 801 * L<File::KDBX::Entry>
 802 * L<File::KDBX::Group>
 803
 804 There is some functionality shared by both types of objects, and that's what this class provides.
 805
 806 Each object can be connected with a L<File::KDBX> database or be disconnected. A disconnected object exists in
 807 memory but will not be persisted when dumping a database. It is also possible for an object to be connected
 808 with a database but not be part of the object tree (i.e. is not the root group or any subroup or entry).
 809 A disconnected object or an object not part of the object tree of a database can be added to a database using
 810 one of:
 811
 812 =for :list
 813 * L<File::KDBX/add_entry>
 814 * L<File::KDBX/add_group>
 815 * L<File::KDBX::Group/add_entry>
 816 * L<File::KDBX::Group/add_group>
 817 * L<File::KDBX::Entry/add_historical_entry>
 818
 819 It is possible to copy or move objects between databases, but B<DO NOT> include the same object in more
 820 than one database at once or there could some strange aliasing effects (i.e. changes in one database might
 821 effect another in unexpected ways). This could lead to difficult-to-debug problems. It is similarly not safe
 822 or valid to add the same object multiple times to the same database. For example:
 823
 824     my $entry = File::KDBX::Entry->(title => 'Whatever');
 825
 826     # DO NOT DO THIS:
 827     $kdbx->add_entry($entry);
 828     $another_kdbx->add_entry($entry);
 829
 830     # DO NOT DO THIS:
 831     $kdbx->add_entry($entry);
 832     $kdbx->add_entry($entry); # again
 833
 834 Instead, do this:
 835
 836     # Copy an entry to multiple databases:
 837     $kdbx->add_entry($entry);
 838     $another_kdbx->add_entry($entry->clone);
 839
 840     # OR move an existing entry from one database to another:
 841     $kdbx->add_entry($entry->remove);
 842
 843 =cut